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Introduction 



The AT&T Transport Interface (TLI) was introduced in UNIX System V Release 
3 as a standard transport-independent programming interface. The Network 
Selection and Name-to- Address Mapping facilities have been added to Release 
4.0 to provide a means of guaranteeing media and protocol independence for 
transport applications. Network Selection and Name-to- Address Mapping allow 
progranm\ers to get transport-specific information to network applications in a 
transport-independent way. 

As part of the unificatibn of UNIX System V and Berkeley UNIX, the sockets 
interface and support for the DARPA protocols (the TCP/IP Internet Package) 
have also been added to System V Release 4.0. 

Both TLI and sockets provide a programming interface to the transport layer. 
In System V Release 4.0, both are implemented within the STREAMS frame- 
work. They differ in the following ways: 

■ TLI is media- and protocol-independent. It allows applications to run 
over any transport protocol that supports the TLI interface. 

■ The sockets interface has historically been tied to the Internet protocol 
suite, TCP/IP and UDP/IP. 

It is expected that new applications will take advantage of TLFs protocol 
indep)endence and that the socket interface will be used primarily in expanding 
and maintaining existing sockets-based applications. 

Organization of the Document 

The document contains this Introduction and three major chapters. Chapter 2, 
'Transport Interface Programming/' describes the UNIX System Transport 
Interface (TLI). 

Chapter 3, "The Sockets Interface/' describes the socket-based interface to the 
transport layer. 

Chapter 4, "Sockets Migration and Sockets-to-TLI Conversion," describes the 
differences between the TLI and sockets interfaces and shows how BSD sockets 
applications can be adapted to System V Release 4, and how sockets applica- 
tions, whether Berkeley- or System V-based, can be modified to run under TLI. 
The chapter includes parallel code examples and tables of equivalent sockets 
and TLI functions. 
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Network Selection and Name-to-Address Mapping 

TLI applications require an understanding of the Network Selection and Name- 
to-Address Mapping facilities provided with this release if they are to run as 
media- and protocol-independent applications. Network Selection provides a 
standard interface to the networks available in any current environment. 
Name-to-Address Mapping allows applications to translate transport-specific 
addresses. The following material is available: 

■ Programmer's Guide: Networking Interfaces. Chapter 8, "Network Selection 
and Name-to-Address Mapping." This chapter provides comprehensive 
coverage of these facilities. 

■ System Administrator's Guide. Chapter 10, "Network Services." The 
description of the Network Selection and Name-to-Address Mapping facil- 
ities is intended for administrators and does not include complete descrip- 
tions of the library routines. 

■ Programme/ s Guide: Networking Interfaces. The following manual pageis are 
included at the end of the Network Selection and Name-to-Address Map- 
ping chapter: 

□ getnetconf ig(3N). Describes the Network Selection library routines 
that manipulate the network configuration administrative file, 
netconfig. 

□ getnetpath(3N). Describes the routines that manipulate the NET- 
PATH variable. The NETPATH environment variable allows pro- 
grammers to choose the networks in the netconfig file that an 
application is to try. 

□ netconf ig(4). Describes the network configuration database file. 

□ enviroh(5). Describes the NETPATH environment variable. 

□ netdirON). Contains descriptions of the Name-to-Addreiss Map- 
ping library functions. 
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Introduction 



This chapter provides detailed information, with various examples, on the UNIX 
system Transport Interface. This interface is intended to supersede the socket- 
based interprocess communications mechanisms as the standard means of gain- 
ing direct access to transport services. 

The following discussion assumes a working knowledge of UNIX system and C 
language programming and data communication concepts. Familiarity with the 
Reference Model of Open Systems Interconnection (OSI) is required as well. 
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Background 



To place the Transport Interface in perspective, a discussion of the OSI Reference 
Model is first presented. The Reference Model partitions networking functions 
into seven layers, as depicted in Figure 2-1. 



Figure 2-1 : OSI Reference Model 
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The physical layer is responsible for the transmission of raw 
data over a communication medium. 

The data link layer provides the exchange of data between net- 
work layer entities. It detects and corrects any errors that may 
occur in the physical layer transmission. 

The network layer manages the operation of the network. In 
particular, it is responsible for the routing and management of 
data exchange between transport layer entities within the net- 
work. 

The transport layer provides transparent data transfer services 
between session layer entities by relieving them jfrpm concerns 
of how reliable and cost-effective transfer of data is achieved. 
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Layer 2 

Layer 3 
Layer 4 
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Layer 5 The session layer provides the services needed by presentation 

layer entities tiiat enable them to organize and synchronize their 
dialogue and manage their data exchange. 

Layer 6 The presentation layer manages the representation of informa- 

tion that application layer entities either conununicate or refer- 
ence in their communication. 

Layer 7 The application layer serves as the window between correspond- 

ing application processes that are exchanging information. 

A basic principle of the Reference Model is that each layer provides services 
needed by the next higher layer in a way that frees the upper layer from con- 
cern about how these services are provided. This approach simplifies the design 
of each particular layer. 

Industry standards either have been or are being defined at each layer of the 
Reference Model. Two standards are defined at each layer: one that specifies an 
interface to the services of the layer, and one that defines the protocol by which 
services are provided. A service interface standard at any layer frees users of 
the service from details of how that layer's protocol is implemented, or even 
which protocol is used to provide the service. 

The transport layer is important because it is the lowest layer in the Reference 
Model that provides the basic service of reliable, end-to-end data transfer 
needed by applications and higher layer protocols. In doing so, this layer hides 
the topology and characteristics of the underlying network from its users. More 
important, however, the transport layer defines a set of services common to 
layers of many contemporary protocol suites, including the International Stan- 
dards Organization (ISO) protocols, the Transmission Control Protocol and Inter- 
net Protocol (TCP/IP) of the ARPANET, Xerox Network Systems (XNS), and the 
Systems Network Architecture (SNA). 

A transport service interface, then, enables applications and higher layer proto- 
cols to be implemented without knowledge of the underlying protocol suite. 
That is a principle goal of the UNIX system Transport Interface. Also, because 
an inherent characteristic of the transport layer is that it hides details of the 
physical medium being used, the Transport Interface offers both protocol and 
medium independence to networking applications and higher layer protocols. 
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The UNIX system Transport Interface was modeled after the industry standard 
ISO Transport Service Definition (ISO 8072). As such, it is intended for those 
applications and protocols that require transport services. Because the Tran- 
sport Interface provides reliable data transfer, and because its services are com- 
mon to several protocol suites, many networking applications will find these 
services useful. 

The Transport Interface is implemented as a user library using the STREAMS 
input/output mechanism. Therefore, many services available to STREAMS appli- 
cations are also available to users of the Transport Interface. These services will 
be highlighted throughout this guide. For detailed information about STREAMS, 
see the DDI Driver-Kernel Interface (DDI/DKI) Reference Manual or the 
Programmers Guide: STREAMS, 
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This chapter is organized as follows: 

■ "Overview of the Transport Interface/' a summary of the basic services 
available to Transport Interface users and a presentation of the back- 
ground information needed for the remainder of the section. 

■ "Introduction to Connection-Mode Service," a description of the services 
associated with connection-based (or virtual circuit) communication. 

■ "Introduction to Connectionless-Mode Service/' a description of the ser- 
vices associated with connectionless (or datagram) communication. 

■ "A Read/Write Interface/' a description of how users can use the services 
of read(2) and write (2) to communicate over a transport connection. 

■ "Advanced Topics/' a discussion of important concepts not covered in 
earlier sections. These include asynchronous event handling and process- 
ing of multiple, simultaneous connect requests. 

■ "State Transitions/' which defines the allowable state transitions associ- 
ated with the Transport Interface. 

■ "Guidelines for Protocol Independence/' which establishes necessary 
guidehnes for developing software that can be run without change over 
any transport protocol developed for the TransfK)rt Interface, 

■ "Examples/' which presents the full listing of each programming example 
used throughout the guide. 

■ "Glossary/' a definition of the Transport Interface terms and acronyms 
used in this section. 



This section describes the more important and common facilities of the Tran- 
sport Interface, but is not meant to be exhaustive. Appendix A of this docu- 
ment contains manual pages giving complete descriptions of each Transport 
Interface routine. 
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Overview of the Transport Interface 



This section presents a high level overview of the services of the Transport 
Interface, which supports the transfer of data between two user processes. Fig- 
ure 2-2 illustrates the Transport Interface. 

Figure 2-2: Transport Interface 
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The transport provider is the entity that provides the services of the Transport 
Interface, and the transport user is the entity that requires these services. An 
example of a transport provider is the ISO transport protocol, while a transport 
user may be a networking application or session layer protocol. 

The transport user accesses the services of the transport provider by issuing the 
appropriate service requests. One example is a request to transfer data over a 
connection. Similarly, the transport provider notifies the user of various events, 
such as the arrival of data on a connection. 

The Network Services Library of UNIX System V includes a set of functions that 
support the services of the Transport Interface for user processes (see intro(3)). 
These functions enable a user to make requests to the provider and process 
incoming events. Programs using the Transport Interface can link the appropri- 
ate routines as follows: 
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Modes of Service 

The Transport Interface provides two modes of service: 

■ connection-mode 

■ connectionless-mode 

Connection-mode is circuit-oriented and enables the transmission of data over 
an established connection in a reliable, sequenced manner. It also provides an 
identification procedure that avoids the overhead of address resolution and 
transmission during the data transfer phase. This service is attractive for appli- 
cations that require relatively long-lived, datastream-oriented interactions. 

Connectionless-mode, by contrast, is message-oriented and supports data 
transfer in self-contained units with no logical relationship required among mul- 
tiple units. This service requires only a preexisting association between the peer 
users involved, which determines the characteristics of the data to be transmit- 
ted. All the information required to deliver a unit of data (for example, the des- 
tination address) is presented to the transport provider, together with the data 
to be transmitted, in one service access (which need not relate to any other ser- 
vice access). Each unit of data transmitted is entirely self-contained. 
Connectionless-mode service is attractive for applications that: 

■ involve short-term request/response interactions 

■ exhibit a high level of redundancy 

■ are d5mamically reconfigurable 

■ do not require guaranteed, in-sequence delivery of data 
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Connection-Mode Service 

The connection-mode transport service is characterized by four phases: 

■ local management 

■ connection establishment 

■ data transfer 

■ connection release 

Locai Management 

The local management phase defines local operations between a transport user 
and a transport provider. For example, a user must establish a channel of com- 
munication vrith the transport provider, as illustrated in Figure 2-3. Each chan- 
nel between a transport user and transport provider is a unique endpoint of 
communication, and will be called the transport endpoint. The t__open(3N) 
routine enables a user to choose a particular transport provider that will supply 
the connection-mode services, and establishes the transport endpoint. 



Figure 2-3: Channel Between User and Provider 
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Another necessary local function for each user is to establish an identity with 
the transport provider. Each user is identified by a transport address. More 
accurately, a transport address is associated with each transport endpoint, and 
one user process may manage several transport endpoints. In connection-mode 
service, one user requests a connection to another user by specifying that user's 
address. The structure of a transport address is defined by the address space of 
the transport provider. An address may be as simple as a random character 
string (for example, "file_server'0, or as complex as an encoded bit pattern that 
specifies all information needed to route data through a network. Each tran- 
sport provider defines its own mechanism for identif)dng users. Addresses may 
be assigned to each transport endpoint by t_bind(3N). 

In addition to t_open and t_bind, several routines are available to support 
local operations. Table 2-1 summarizes all local management routines of the 
Transport Interface. 



Table 2-1 : Local Management Routines of the Transport Interface 



Command 


Description 


t_alloc 


Allocates Transport Interface data structures. 


t_bind 


Binds a transport address to a transport endpoint. 


t_close 


Qoses a transport endpoint. 


t_error 


Prints a Transport Interface error message. 


t_free 


Frees structures allocated using t_alloc. 


t_getinfo 


Returns a set of parameters associated with a particular 
transport provider. 


t_get state 


Returns the state of a transport endpoint. 
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Table 2-1 : Local Management Routines of the Transport Interface (continued ) 



Command 


Description 


t_look 


Returns the current event on a transport endpoint. 


t_open 


Establishes a transport endpoint connected to a chosen 
transport provider. 


t^optmgint 


Negotiates protocol-specific options with the transport 
provider. 


t_sync 


Synchronizes a transport endpoint with the transport 
provider. 


t_unbind 


Unbinds a transport address from a transport end- 
point. 



Connection Establishment 

The connection establishment phase enables two users to create a connection, or 
virtual circuit, between them, as demonstrated in Figure 2-4. 
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Figure 2-4: Transport Connection 
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This phase is illustrated by a client-server relationship between two transport 
users. One user, the server, typically advertises some service to a group of 
users, and then listens for requests from those users. As each client requires the 
service, it attempts to connect itself to the server using the server's advertised 
transport address. The t_connect(3N) routine initiates the connect request. 
One argument to t_connect, the transport address, identifies the server the 
client wishes to access. The server is notified of each incoming request using 
t_listen(3N), and may call t_accept(3N) to accept the client's request for 
access to the service. If the request is accepted, the transport connection is esta- 
blished. 

Table 2-2 summarizes all routines available for establishing a transport connec- 
tion. 
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Table 2-2: Routines for Establishing a Transport Connection 



Command 


Description 


t_accept 


Accepts a request for a transport connection. 


t_connect 


Establishes a connection with the transport user at a 
specified destination. 


t_listen 


Retrieves an indication of a connect request from 
another transport user. 


t_rcvconnect 


Completes connection establishment if t_connect was 
called in asynchronous mode (see the section 
"Advanced Topics"). 



Data Transfer 

The data transfer phase enables users to transfer data in both directions over an 
established connection. Two routines, t_snd(3N) and t_rcv(3N), send and 
receive data over this connection. All data sent by a user is guaranteed to be 
delivered to the user on the other end of the connection in the order in which it 
was sent. Table 2-3 summarizes the connection mode data transfer routines. 



Table 2-3: Connection Mode Data Transfer Routines 



Command 


Description 


t__rcv 


Retrieves data that has arrived over a transport connec- 
tion. 


t_snd 


Sends data over an estabUshed transport connection. 
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Connection Release 

The connection release phase allows you to break an established connection. 
When you decide that a conversation should end, you can request that the pro- 
vider release the transport connection. Two types of connection release are sup- 
ported by the Transport Interface. The first is an abortive release, which directs 
the transport provider to release the connection immediately. Any previously 
sent data that has not yet reached the other transport user may be discarded by 
the transport provider. The t_snddis(3N) routine initiates this abortive 
disconnect, and t_rcvdis(3N) processes the incoming indication for an abor- 
tive disconnect. 

All transport providers must support the abortive release procedure. In addi- 
tion, some transport providers may also support an orderly release facility that 
enables users to terminate communication gracefully with no data loss. The 
functions t_sndrel(3N) and t_rcvrel(3N) support this capability. Table 2-4 
summarizes the connection release routines. 



Table 2-4: Connection Release Routines 



Command 


Description 


t_rcvdis 


Returns an indication of an aborted connection, includ- 
ing a reason code and user data. 


t_rcvrel 


Returns an indication that the remote user has 
requested an orderly release of a connection. 


t_snddis 


Aborts a connection or rejects a connect request. 


t_sndrel 


Requests the orderly release of a . connection. 
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Connectionless-Mode Service 

The connectionless-mode transport service is characterized by two phases: local 
management and data transfer. The local management phase defines the same 
local operations described above for the connection-mode service. 

The data transfer phase enables a user to transfer data units (sometimes called 
datagrams) to the specified peer user. Each data unit must be accompanied by 
the transport address of the destination user. Two routines, t_sndudata(3N) 
and t_rcvudata(3N), support this message-based data transfer facility. Table 
2-5 summarizes all routines associated with connectionless-mode data transfer. 



Table 2-5: Routines for Connectionless-Mode Data Transfer 



Command 


Description 


t_rcvudata 


Retrieves a message sent by another transport user. 


t__rcvuderr 


Retrieves error information associated with a previ- 
ously sent message. 


t_sndudata 


Sends a message to the specified destination user. 



State Transitions 

The Transport Interface has two components: 

■ the library routines that provide the transport services to users 

■ the state transition rules that define the sequence in which the transport 
routines may be invoked 

The state transition rules can be found later in this chapter in the state tables in 
the section "State Transitions." The state tables define the legal sequence of 
library calls based on state information and the handling of events. These 
events include user-generated library calls, as well as provider-generated event 
indications. 
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Any user of the Transport Interface must connpletely understand all possible 
state transitions before writing software using the interface. 
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This section describes the connection-mode service of the Transport Interface. 
As discussed in the previous section, the connection-mode service can be illus- 
trated using a client-server paradignrL The important concepts of connection- 
mode service will be presented using two programming examples. The exam- 
ples are related: the first example illustrates how a client establishes a connec- 
tion to a server and then communicates with it; the second example shows the 
server's side of the interaction. All examples discussed in this chapter are 
presented complete later in the section "Some Examples.'' 

In the examples, the client establishes a connection with a server process. The 
server then transfers a file to the client. The client, in turn, receives the data 
from the server and writes it to its standard output file. 



Local Management 

Before the client and server can establish a transport connection, each must first 
establish a local channel (the transport endpoint) to the transport provider using 
t_open, and establish its identity (or address) using t_bind. 

The set of services supported by the Transport Interface may not be imple- 
mented by all transport protocols. Each transport provider has a set of charac- 
teristics associated with it that determines the services it offers and the limits 
associated with those services. This information is returned to the user by 
t_open, and consists of the following: 

addr maximum size of a transport address 

options maximum bytes of protocol-specific options that may be passed 
between the transport user and transport provider 

tsdu maximum message size that may be transmitted in either 

connection-mode or connectionless-mode 

etsdu maximum expedited data message size that may be sent over a 

transport connection 

connect maximum number of bytes of user data that may be passed 
between users during connection establishment 
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discon maximum bytes of user data that may be passed between users 

during the abortive release of a connection 

servtype the type of service supported by the transport provider 

The three service types defined by the Transport Interface are: 

T_COTS The transport provider supports connection-mode service but 

does not provide the optional orderly release facility. 

T_COTS_ORD The transf>ort provider suppyorts connection-mode service with 
the optional orderly release facility. 

T_CLTS The transport provider supports connectionless-mode service. 

Only one such service can be associated with the transport pro- 
vider identified by t_open. 



t_open returns the default provider characteristics associated with a tran- 
NOTE sport endpoint. However, some characteristics may change after an end- 
point has been opened. This will occur if the characteristics are associated 
with negotiated options (option negotiation is described later in this section). 
' For example, if the support of expedited data transfer is a negotiated option, 
the value of this characteristic may change. t__getinf o may be called to 
retrieve the current characteristics of a transport endpoint. 



Once a user establishes a transport endpoint with the chosen transport provider, 
it must establish its identity. As mentioned earlier, t_bind does this by bind- 
ing a transport address to the transport endpoint. In addition, for servers, this 
routine informs the transport provider that the endpoint vdll be used to listen 
for incoming connect indications, also called connect requests. 

An optional facility, t^optmgmt (3N), is also available during the local manage- 
ment phase. It enables a user to negotiate the values of protocol options with 
the transport provider. Each transport protocol is expected to define its own set 
of negotiable protocol options, which may include such information as Quality- 
of-Service parameters. Because of the protocol-specific nature of options, only 
applications written for a particular protocol environment are expected to use 
this facility. 



Transport Interface Programming 



2-17 



Introduction to Connection-Mode Service 



The Client 

The local management requirements of the example client and server are used 
to discuss details of these facilities. The following are the definitions needed by 
the client program, followed by its necessary local management steps. 



#lnclxKie <3t<3io^h> 
llnclude <fcntl.h> 
Idef ine SEdJt KCXHR 


1 


/ 


mini) 
{ 




















int 
int 


fd; 

nbyt^d; 
flags » d; 
b«f[l0243 





/★ server's meXX )cndWn address ^/ 



struct t_^call *sndcall; 
extern int tjBrmo; 

if <(fd * t^openC'/dev/tivc", 0_RCWR, NOLL)) < 0) { 
tjerror(«*tj3pen failed"*); 
exit(X); 

if (t_bind<fd, NULL, MXLL) < 0> { 
tjarror("t_bind failed"); 

mmmmmm^ 



The first argument to t_open is the pathname of a file system node that 
identifies the transport protocol that will supply the transport service. In this 
example, /dev/tivc is a STREAMS clone device node that identifies a generic, 
connection-based transport protocol (see clone (4)). The clone device finds an 
available minor device of the transport provider for the user. It is opened for 
both reading and writing, as specified by the 0_RDWR open flag. The third 
argument may be used to return the service characteristics of the transport pro- 
vider to the user. This information is useful when writing protocol-independent 
software (discussed in the section "Guidelines for Protocol Independence," 
below). For simplicity, the client and server in this example ignore this informa- 
tion and assume the transport provider has the following characteristics: 
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■ The transport address is an integer value that uniquely identifies each 
user. 

■ The transport provider supports the T_COTS_ORD service tj^, and the 
example will use the orderly release facility to release the connection. 

■ User data may not be passed between users during either connection 
establishment or abortive release. 

■ The transport provider does not support protocol-specific options. 

Because these characteristics are not needed by the user, NULL is specified in the 
third argument to t_open. If the user needed a service other than 
T_COTS_pRD, another transport provider would be opened. An example of the 
T_CLTS service invocation is presented in the section "Introduction to 
Connectionless-Mode Service." 

The return value of t_open is an identifier for the transport endpoint that will 
be used by all subsequent Transport Interface function calls. This identifier is 
actually a file descriptor obtained by opening the transport protocol file (see 
open(2)). The significance of this fact is highlighted in the section "A 
Read/Write Interface." 

After the transport endpoint is created, the client calls t_bind to assign an 
address to the endpoint. The first argument identifies the transport endpoint. 
The second argument describes the address the user would like to bind to the 
endpoint, and the third argument is set on return from t_bind to specify the 
address that the provider bound. 

The address associated with a server's transport endpoint is important, because 
that is the address used by all clients to access the server. However, the typical 
client does not care what its own address is, because no other process will try to 
access it. That is the case in this example, where the second and third argu- 
ments to t_bind are set to NULL. A NULL second argument directs the tran- 
sport provider to choose an address for the user. A NULL third argument 
specifies that the user does not care what address was assigned to the endpoint. 

If either t_open or t_bind fail, the program will call t_error(3N) to print an 
appropriate error message to stderr . If any Transport Interface routine fails, 
the global integer t_errno will be assigned a transport error value. A set of 
error values has been defined (in <tiuser . h>) for the Transport Interface, and 
t_error will print an error message corresponding to the value in t__errno. 
This routine is analogous to perrorO), which prints an error message based on 
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the value of errno. If the error associated with a transport function is a system 
error, t_errno will be set to TSYSERR, and errno will be set to the appropri- 
ate value. 



The Server 

The server in this example must take similar local management steps before 
communication can begin. The server must establish a transport endpoint 
through which it will listen for connect indications. The necessary definitions 
and local management steps are shown below: 



#incliide <tiuset 


,h> 


flnclude <»t^:iopt5.h> 


♦include <fcntX. 


h> 


#inclT«S9 <9tdio. 


h> 


#inclu<}e <signal 




#define 


DISCONNECT -3 






int connjfd; 






esttem int t. 


ermo; 


ntainO 









/* server's well ktiom address */ 



/* connection established here */ 



int Xisten^fd; 
struct tjsind *bind/ 
struct t call *call; 



/* listening transport enci^lttt */ 



if ((listen^fd * t_opeQ("/dev/tivc", 
OJRDWR, NUW.)) < 0) { 

tjSrr<Jr(*'tj6pen failed for listeft^fd-); 
eJlt(l); 



* assuming that the address is an integer value, 

* thia program may not run over another protocol. 

if ((bind - (struct tj>ind *)t_alloc(listen__fd, 

t error (*'t alloc of t bind structure failed**); 
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mit (2); 

liiiiiiiiiiiiiiiiiiiii^ 

bin4-^>adctr«leii « 9izeQf (inty ; 



i£ (thlndaiBteii__f4, biiKi* bind) < 0) { 

terror <«tJ)lRd faUod for ll3tenJ5d*»); 



exit (3); 



* Waa tbe correct a^cieeaa bound? 

liiiiiiiiiiliiiiiliiiiiii 

if (♦(int *)bind->addr.buf I- SRV_ADDR> { 

fprintf <stderry *^J>ind bound vrong addressXn*'); 



exit<4>; 



J 



As with the client, the first step is to call t_open to establish a transport end- 
point with the desired transport provider. This endpoint, listen_f d, will be 
used to listen for connect indications. Next, the server must bind its well- 
known address to the endpoint. This address is used by each client to access 
the server. The second argument to t_bind requests that a particular address 
be bound to the transport endpoint. This argument points to a t_bind struc- 
ture with the following format: 



struct t_bind { 

struct netbuf addr; 



imsicped qlen; 



) 



where addr describes the address to be bound, and qlen specifies the max- 
imum outstanding connect indications that may arrive at this endpoint. All 
Transport Interface structure and constant definitions are found in 
<tiuser .h>. 
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The address is specified using a netbuf structure that contains the following 
members: 



iUi5l^tne($ Int Ai^ucl^; 
unsigned Int lemi 
<2ihar *buf i 

■iiiiiliiiiiiiiiiiiliiliili 



where buf points to a buffer containing the data, len specifies the bytes of data 
in the buffer, and maxlen specifies the maximum bytes the buffer can hold (and 
need only be set when data is returned to the user by a Transport Interface rou- 
tine). For the t__bind structure, the data pointed to by buf identifies a tran- 
sport address. It is expected that the structure of addresses will vary among 
each protocol implementation under the Transport Interface. The netbuf struc- 
ture is intended to support any address structure. 

If the value of qlen is greater than 0, the transport endpoint may be used to 
listen for connect indications. In such cases, t_bind directs the transport pro- 
vider to begin queueing connect indications destined for the bound address 
immediately. Furthermore, the value of qlen specifies the maximum outstand- 
ing connect indications the server wishes to process. The server must respond 
to each connect indication, either accepting or rejecting the request for connec- 
tion. An outstanding connect indication is one to which the server has not yet 
responded. Often, a server will fully process a single connect indication and 
respond to it before receiving the next indication. When this occurs, a value of 
1 is appropriate for qlen. However, some servers may wish to retrieve several 
connect indications before responding to any of them. In such cases, qlen 
specifies the maximum number of outstanding indications the server will pro- 
cess. An example of a server that manages multiple outstanding connect indica- 
tions is presented in the section "Advanced Topics." 

t_alloc(3N) is called to allocate the t_bind structure needed by t__bind. 
t_alloc takes three arguments. The first is a file descriptor that references a 
transport endpoint. This is used to access the characteristics of the transport 
provider (see t_open(3N)). The second argument identifies the appropriate 
Transport Interface structure to be allocated. The third argument specifies 
which, if any, netbuf buffers should be allocated for that structure. T_ALL 
specifies that all netbuf buffers associated with the structure should be 



2-22 



Programmer's Guide: Networlcing Interfaces 



Introduction to Connection-Mode Service 



allocated, and causes the addr buffer to be allocated in this example. The size 
of this buffer is determined from the transport provider characteristic that 
defines the maximum address size. The maxlen field of this netbuf structure 
will be set to the size of the newly allocated buffer by t_alloc. The use of 
t^alloc helps ensure the compatibility of user programs with future releases 
of the Transport Interface. 

The server in this example processes connect indications one at a time, so qlen 
is set to 1. The address information is then assigned to the newly allocated 
t_bind structure. This t_bind structure passes information to t_bind in the 
second argument and returns information to the user in the third argument. 

On return, the t_bind structure contains the address that was bound to the 
transport endpoint. If the provider could not bind the requested address 
(perhaps because it had been bound to another transport endpoint), it will 
choose another appropriate address. 



NOTE 



Each transport provider manages its address space differently. Some tran- 
sport providers may allow a single transport address to be bound to several 
transport endpoints, while others may require a unique address per endpoint. 
The Transport Interface supports either choice. Based on its address 
' management rules, a provider will determine if it can bind the requested 
address. If not, it will choose another valid address from its address space 
and bind it to the transport endpoint. 

The server must check the bound address to ensure that it is the one previously 
advertised to clients. Otherwise, the clients will be unable to reach the server. 

If t_bind succeeds, the provider will t>egin queueing connect indications, 
entering the next phase of communication, connection establishment. 



Connection Establishment 



The connection establishment procedures highlight the distinction between 
clients and servers. The Transport Interface imf)oses a different set of pro- 
cedures in this phase for each type of transport user. The client starts the con- 
nection establishment procedure by requesting a connection to a particular 
server using t_conriect(3N). The server is then notified of the client's request 
by calling t_listen(3N). The server may either accept or reject the client's 
request. It will call t_accept(3N) to establish the connection, or call 
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t_snddis(3N) to reject the request. The client will be notified of the server's 
decision when t_connect completes. 

The Transport Interface supports two facilities during connection establishment 
that may not be supported by all transport providers: 

■ The ability to transfer data between the client and server when establish- 
ing the connection. 

The client may send data to the server when it requests a connection. 
This data will be passed to the server by t_listen. Similarly, the server 
can send data to the client when it accepts or rejects the connection. The 
connect characteristic returned by t_open determines how much data, if 
any, two users may transfer during connect establishment. 

■ The negotiation of protocol options. 

The client may specify protocol options that it would like the transport 
provider and /or the remote user to support. The Transport Interface sup- 
ports both local and remote option negotiation. As discussed earlier, 
option negotiation is inherently a protocol-specific function. Use of this 
facility is discouraged if protocol independent software is a goal (see the 
section "Guidelines for Protocol Independence"). 

The Client 

Continuing with the client/server example, the steps needed by the client to 
establish a connection are shown next: 
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Bs^ adduming that ttm tOdxean in «n int^^r v^lI^h^, 

iiii^iiiiliiiiiiiiiiil 
liiiililliiiillillB^^^ 

4n(|Qall^>ackir.l^ « sizeof (int); 
*ant *)sndcaXX->a<3dr.buf ^ SRVADDR; 

If (t_connect(f<ai/ sndcall, TOi) < 0) { 

tjartorrtjcowi^ failed for f<J*); 



The t_connect call establishes the connection with the server. The first argu- 
ment to t_connect identifies the transport endpoint through which the con- 
nection is established, and the second argument identifies the destination server. 
This argument is a pointer to a t_call structure with the following format: 



struct t^call { 

atrqct hetJjuf adtdr; 
struct xxetbuf <^t; 
struct netbuf udata; 
int se<3a«noe; 



addr identifies the address of the server, opt may be used to specify protocol- 
specific options that the client would like to associate with the connection, and 
udata identifies user data that may be sent with the connect request to the 
server. The sequence field has no meaning for t_connect . 

t_alloc is called above to allocate the t_call structure dynamically. Once 
allocated, the appropriate values are assigned. In this example, no options or 
user data are associated with the t_connect call, but the server's address must 
be set. The third argument to t_alloc is set to T__ADDR to specify that an 
appropriate netbuf buffer should be allocated for the address. The server's 
address is then assigned to buf , and len is set accordingly. 
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The third argument to t_cpnnect can be used to return information about the 
newly established connection to the user, and may retrieve any user data sent 
by the server in its response to the connect request. It is set to NULL by the 
client here to indicate that this information is not needed. The connection will 
be established on successful return of t_connect . If the server rejects the con- 
nect request, t_c6nnect will fail and set t^errno to TLCX)K. 



Event Handling 

The TLOOK error has special significance in the Transport Interface. TLOOK 
notifies the user if a Transport Interface routine is interrupted by an unexpected 
asynchronous transport event on the given transport endpoint. As such, TLOOK 
does not report an error with a Transport Interface routine, but the normal pro- 
cessing of that routine will not be done because of the pending event. The 
events defined by the Transport Interface are listed here: 

A request for a connection, called a connect indication, 
has arrived at the transport endpoint. 

The confirmation of a previously sent connect request, 
called a connect confirmation, has arrived at the tran- 
sport endpoint. The confirmation is generated when a 
server accepts a connect request. 

User data has arrived at the transport endpoint. 

Expedited user data has arrived at the transport end- 
point. Expedited data will be discussed later in this sec- 
tion. 

A notification that the connection was aborted or that 
the server rejected a connect request, called a disconnect 
indication, has arrived at the transport endpoint. 

A request for the orderly release of a connection, called 
an orderly release indication, has arrived at the tran- 
sport endpoint. 

The notification of an error in a previously sent 
datagram, called a unitdata error indication, his arrived 
at the transport endpoint (see the section "Introduction 
to Connectionless-Mode Service"). 



T^LISTEN 
T__CONNECT 

T_DATA 
T_EXDATA 

T_DISCONNECT 

T_ORDREL 

T UDERR 
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It is possible in some states to receive one of several asynchronous events, as 
described in the state tables of the section "State Transitions/' The t_look(3N) 
routine enables a user to determine what event has occurred if a TLOOK error is 
returned. The user can then process that event accordingly. In the example, if a 
connect request is rejected, the event passed to the client v^U be a disconnect 
indication. The client will exit if its request is rejected. 



The Server 

Returning to the example, when the client calls t_connect, a connect indica- 
tion will be generated on the server's listening transport endpoint. The steps 
required by the server to process the event are discussed below. For each client, 
the server accepts the connect request and spawns a server process to manage 
the connection. 



If ((call m (struct t_call *)t_allQc(Uaten_fd, t_CALL, 1?Jffi>> N""^> ^ 
t_error(''t alloc of t call stractune failed**); 



exit (5); 



mmmMm 

while <1) { 



if (t__listen(listen_fd, call) < 0) { 

t enx>r<'»t listen failed for listen fd**); 



exit (€> ; 



if {(connfd * accept_call (listen_fd, call)) !» DISCCXINECT) 
run_server(listen_fd) ; 



The server will loop forever, processing each connect indication. First, the 
server calls t_listen to retrieve the next connect indication. When one 
arrives, the server calls accept_call to accept the connect request. 
accept_call accepts the connection on an alternate transport endpoint (as dis- 
cussed below) and returns the value of that endpoint. conn_f d is a global vari- 
able that identifies the transport endpoint where the connection is established. 
Because the connection is accepted on an alternate endpoint, the server may 
continue listening for connect indications on the endpoint that was bound for 
listening. If the call is accepted without error, run_server will spawn a pro- 
cess to manage the connection. 



Transport Interface Programming 



2-27 



introduction to Connection-li/lode Service 



The server allocates a t_call structure to be used by t_listen. The third 
argument to t_alloc, T_ALL, specifies that all necessary buffers should be 
allocated for retrieving the caller's address, options, and user data. As men- 
tioned earlier, the transport provider in this example does not support the 
transfer of user data during connection establishment, and also does not support 
any protocol options. Therefore, t_alloc will not allocate buffers for the user 
data and options. It must, however, allocate a buffer large enough to store the 
address of the caller. t_alloc determines the buffer size from the addr 
characteristic returned by t_open. The maxlen field of each netbuf structure 
will be set to the size of the newly allocated buffer by t_alloc (maxlen is 0 
for the user data and options buffers). 

Using the t_call structure, the server calls t_listen to retrieve the next con- 
nect indication. If one is currently available, it is returned to the server immedi- 
ately. Otherwise, t_listen will block until a connect indication arrives. 



NOTE 











The TransfX)rt Interface supports an asynchronous mode for these routines, 
which prevents a process from blocking. This feature is discussed in the 
section "Advanced Topics." 



When a connect indication arrives, the server calls accept_call to accept the 
client's request, as follows: 
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acceptjciaiX (Xistenjrd, caai) 
int Il3t6n_£d; 
struct t calj. *calX; 

llllllllllllllllllllll 
int resfd; 



if ((tesfd * t_open<«/dav/tive**, OJ«)WR, NULL)) < 0) { 
t_error(^tjDp^ for re3ponding fd failed"); 
exit (7); 



if (tj>ind(r^sfd, HOIX, mm < 0) { 

tjerrori^tjaind for respondin? failed**); 



if (tjaccept (lii(ten_f d, resfd, call) < 0) { 

if (tjsrrno « HOOK) i /* mat be a disconnect */ 
if (t_r«?vdi3(ll«ten_fd* NOLL) < 0) { 

t_drror<«t_rcvdid failed ^or lidtenfd**); 
€ait(9); 

if (tjclose(re3fd) < 0) { 

t_erxor("tj2lose failed for responding fd"); 
exit (10); 

/♦ qo back up and listen for otber c*Xl« */ 
rettixn (D1S0C«WECT) ; 

t_errorC»t_accept failed") ; 
exit (11) ; 

retiaxn(resfd); 

V J 

accept_call takes two arguments. 

■ listen_f d identifies the transport endpoint where the connect indication 
arrived 

■ call is a pointer to a t_call structure that contains all information 
associated with the connect indication. 
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1 

The server first establishes another transport endpoint by opening the clone dev- 
ice node of the transport provider and binding an address. As with the client, a 
NULL value is passed to t_bind to specify that the user does not care what 
address is bound by the provider. The newly established transport endpoint, 
resf d, is used to accept the client's connect request 

The first two argunnents of t_accept specify the listening transport endpoint 
and the endpoint where the connection will be accepted, respectively. A con- 
nection may be accepted on the listening endpoint, but this prevents other 
clients from accessing the server for the duration of the connection. 

The third argument of t_accept points to the t_call structure associated 
with the connect indication. This structure should contain the address of the 
calling user and the sequence number returned by t_listen. The value of 
sequence is significant if the server manages multiple outstanding connect 
indications. The "Advanced Topics" section presents an example of this situa- 
tion. Also, the t_call structure should identify protocol options the user 
would like to specify, and user data that may be passed to the client. Because 
the transport provider in this example does not support protocol options or the 
transfer of user data during connection establishment, the t__call structure 
returned by t_listen may be passed without change to t_accept. 

For simplicity in the example, the server will exit if either the t_open or 
t_bind call fails, exit (2) will close the transport endpoint associated with 
listen__f d, causing the transport provider to pass a disconnect indication to 
the client that requested the connection. This disconnect indication notifies the 
client that the connection was not established; t_connect will fail, setting 
t_errno to TLOOK. 

t_accept may fail if an asynchronous event has occurred on the listening tran- 
sport endpoint before the connection is accepted, and t_errno will be set to 
TLOOK. The state transition table in the "State Transitions" section shows that 
the only event that may occur in this state with only one outstanding connect 
indication is a disconnect indication. This event may occur if the client decides 
to undo the connect request it had previously sent. If a disconnect indication 
arrives, the server must retrieve the disconnect indication using t_rcvdis. 
This routine takes a pointer to a t_discon structure as an argument, which is 
used to retrieve information associated with a disconnect indication. In this 
example, however, the server does not care to retrieve this information, so it 
sets the argument to NULL. After receiving the disconnect indication. 
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accept_call doses the responding transport endpoint and returns DISCON- 
NECT, which informs the server that the connection was disconnected by the 
client. The server then listens for further connect indications. 

Figure 2-5 illustrates how the server establishes connections. 
Figure 2-5: Listening and Responding Transport Endpoints 



client 



server 



responding^ 
endpoint 



transport provider 



listening 
endpoint 



Transport Interface 



transport 
connection 



The transport connection is established on the newly created responding end- 
point, and the listening endpoint is freed to retrieve further connect indications. 

Data Transfer 

Once the connection has been established, both the client and server n\ay begin 
transferring data over the connection using t_snd and t_rcv. The Transport 
Interface does not differentiate the client from the server from this point on. 
Either user may send and receive data, or release the connection. The Transport 
Interface guarantees reliable, sequenced delivery of data over an existing con- 
nection. 
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Two classes of data may be transferred over a transport connection: 

■ normal data 

■ expedited data 

Expedited data is typically associated with urgent information. The exact 
semantics of expedited data are subject to the interpretations of the transport 
provider. Furthermore, not all transport protocols support the notion of an 
expedited data class (see t_open(3N)). 

All transport protocols support the transfer of data in byte stream mode, where 
"byte stream" implies no concept of message boundaries on data that are 
transferred over a connection. However, some transport protocols support the 
preservation of message boundaries over a transport connection. This service is 
supported by the Transport Interface, but protocol-independent software must 
not rely on its existence. 

The message interface for data transfer is supported by a special flag of t_snd 
and t_rcv called T__MORE. The messages, called Transport Service Data Units 
(TSDU), may be transferred between two transport users as distinct units. The 
maximum size of a TSDU is a characteristic of the underlying transport protocol. 
This information is available to the user from t_open and t_getinf o. 
Because the maximum TSDU size can be large (possibly unlimited), the Tran- 
sport Interface allows a user to transmit a message in multiple units. 

To send a message in multiple units over a transport connection, the user must 
set the T_MORE flag on every t_snd call except the last. This flag specifies that 
the user will send more data associated with tiie message in a subsequent call to 
t_snd. The last message unit should be transmitted with T_MORE turned off to 
specify that this is the end of the TSDU. 

Similarly, a TSDU may be passed in multiple units to the receiving user. Again, 
if t__rcv returns with the T_MORE flag set, the user should continue calling 
t_rcv to retrieve the remainder of the message. Th^ last unit in the message 
will be identified by a call to t_rcv that does not set T_MORE. 
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The T_MORE flag implies nothing about how the data may be packaged 
below the Transport Interface or how the data may be delivered to the 
remote user. Each transport protocol, and each implementation of that 
protocol, may package and deliver the data differently. 

For example, if a user sends a complete message in a single call to 
t_snd, there is no guarantee that the transport provider will deliver the 
data in a single unit to the remote transport user. Similarly, a TSDU 
transmitted in two message units may be delivered in a single unit to the 
remote transport user. The message boundaries may only be preserved 
by noting the value of the T_MORE flag on t_snd and t_rcv. This will 
guarantee that the receiving user will see a message with the same con- 
tents and message boundaries as was sent by the remote user. 



The Client 

Continuing with the client /server example, the server will transfer a log file to 
the client over the transport connection. The client receives this data and writes 
it to its standard output file. A byte stream interface is used by the client and 
server, where message boundaries (that is, the T_MORE flag) are ignored. The 
client receives data using the following instructions: 

wMI« Unbytea • t_rcv<fd, buf, 1024, fiflags)) -1) { 
if (f write (buf, X, nbytes, atdout) < 0) { 

fprintf (stderr, •'fwrite f^iXea\n->; 
exit(5); .. 

\ : J 

The client continuously calls t_rcv to process incoming data. If no data is 
currently available, t_rcv blocks until data arrives. t_rcv retrieves the avail- 
able data up to 1024 bytes, which is the size of the client's input buffer, and 
returns the number of bytes received. The client then writes this data to stan- 
dard output and continues. The data transfer phase will complete when t_rcv 
fails. t_rcv will fail if an orderly release or disconnect indication arrives, as 
discussed later in this section. If the fwriteOS) call fails for any reason, the 
client will exit, closing the transport endpoint. If the transport endpoint is 
closed (either by exit or t__close) during the data transfer phase, the connec- 
tion will be aborted and the remote user will receive a disconnect indication. 
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The Server 

Looking now at the other side of the connection, the server manages its data 
transfer by spawning a child process to send the data to the client. The parent 
process then loops back to listen for further connect indications. run_server 
is called by the server to spawn this child process as follows: 



lilililllil 

/* cowi/d 13 global Jdecause nodded here */ 
If itjZokiCCfnXiJ^d} TjDlilOONNBCT) t 

f prlntf (stderir, "connection abortedVn"); 

exit (12); 

/♦ else oiderly release Indication - noxmal exit */ 
exit (0) ; 

rutxjserverdisten^fd) 
int"**ii»ten ^d; 

iiii^iiiiliiiiiii 

int nbytes/ 

pnjB *iogfp; /* file pointer to log file */ 

<shar buf [10241; 

switch (f03*<)) { 



case -It 



perror(*»fork failed*)!; 
exit (20); 



dteitaulti /* patent */ 



/* dose connJTd and then go up and listen again */ 
if <t_elo3e(c^jrd> < 0) ( 



t^error('«t_close failed for conn_fd"); 
€Sit(21) ; 



retwii; 

<»se /* ciiild */ 

/* close listenjfd and do service */ 
if it^close (listenjfd) < Q} { ■ 

tjerror(**tjclose failed for listenjfd'*); 
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f ^ 

if (dogfp- fppeFi("logme% V)) — NOW.) { 
perror<**camot open logfiXe**>; 
exit (23); 

illlllllllijiillilll 

Bignal (SIGPOLL, connrelease) ; 

if (iocti(cotm_fd, I^SerSIG, S_IKE>UT) < 0) { 

pGrror<"ioctl I^SETSIG failed"); 

exit (24); 

if <t^look{conn^fdJ !• 0) ( /♦ was disconnect there? */ 
fprintf (stdaxr, "t^loofc; uneacp©c?ted eventXn'*) ; 
exit (25); 

while ((nbytes * fr»ad(buf, 1, 1024^ logfp)) > 0) 
if (t_»nd(coim_fd. btif, nbytes* 0) < 0) ( 
t_ertorC*t_s»d failed"); 
^it(26); " 

I ' ) 

After the fork, the parent process returns to the main processing l(X)p an<i 
listens for further connect indications. Meanwhile, the child process will 
manage the newly established transport connection. If the fork call fails, exit 
closes the transport endpoint associated with listen_f d, sending a disconnect 
indication to the client, and the client's t_connect call will fail. 

The server process reads 1024 bytes of the log file at a time and sends that data 
to the client using t__snd. buf points to the start of the data buffer, and 
nbytes specifies the number of bytes to be transmitted. The fourth argument 
can contain one of the two optional flags below: 

■ T_EXPEDITED specifies that the data is expedited 

■ T_MORE defines message boundaries when transmitting messages over a 
connection. 

Neither flag is set by the server in this example. 
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If the user floods the transport provider with data, the provider may exert back 
pressure to provide flow control. In such cases, t_snd will block until the flow 
control is relieved, and will then resume its operation. t_snd will not complete 
until nbyte bytes have been passed to the transport provider. 

The t_snd routine does not look for a disconnect indication (showing that the 
connection was broken) before passing data to the provider. Also, because the 
data traffic flows in one direction, the user will never look for incoming events. 
If the connection is aborted, the user should be notified since data may be lost. 
The user can invoke t_look, which checks for incoming events before each 
t_snd call. A more efficient solution is presented in the example. The 
STREAMS INSETS IG ioctl enables a user to request a signal when a given 
event occurs (see streamio(5) and signal (2)). S_INPUT causes a signal to be 
sent to the user if any input arrives on the Stream referenced by conn_f d. If a 
disconnect indication arrives, the signal catching routine (connrelease) prints 
an error message and then exits. 

If the data traffic flowed in both directions in this example, the user would not 
have to monitor the connection for disconnects. If the client alternated t_snd 
and t_rcv calls, it could rely on t_rcv to recognize an incoming disconnect 
indication. 



Connection Release 

At any point during data transfer, either user may release the transport connec- 
tion and end the conversation. As mentioned earlier, two forms of connection 
release are supported by the Transport Interface: 

■ Abortive release breaks a connection immediately and may result in the 
loss of any data that has not yet reached the destination user. 

Either user may call t_snddis to generate an abortive release. Also, the 
transport provider may abort a connection if a problem occurs below the 
Transport Interface. t_snddis enables a user to send data to the remote 
user when aborting a connection. Although the abortive release is sup- 
ported by all transport providers, the abihty to send data when aborting a 
connection is not. 

When the remote user is notified of the aborted connection, t_rcvdis 
must be called to retrieve the disconnect indication. This call returns a 
reason code that identifies why the connection was aborted, and returns 
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any user data that may have accompanied the disconnect indication (if the 
abortive release was initiated by the remote user). This reason code is 
specific to the underlying transport protocol, and should not be inter- 
preted by protocol-independent software. 

■ Orderly release gracefully terminates a connection and guarantees that no 
data will be lost. 

All transport providers must support the abortive release procedure, but orderly 
release is an optional facility that is not supported by all transport protocols. 



The Server 

The client-server example in this section assumes that the transport provider 
supports the orderly release of a connection. When all the data has been 
transferred by the server, the connection may be released as follows: 



if (t_3ndrel(connfcl) < 0) ( 



The orderly release procedure consists of two steps by each user. The first user 
to complete data transfer may initiate a release using t_sndrel, as illustrated 
in the example. This routine informs the client that no more data will be sent 
by the server. When the client receives this indication, it may continue sending 
data back to the server if desired. When all data have been transferred, how- 
ever, the client must also call t_sndrel to indicate that it is ready to release 
the connection. The connection is released only after both users have requested 
an orderly release and received the corresponding indication from the other 
user. 

In this example, data is transferred in one direction from the server to the client, 
so the server does not expect to receive data from the client after it has initiated 
the release procedure. Thus, the server simply calls pause (2) after initiating the 
release. Eventually, the remote user responds with its orderly release request, 
which generates a signal that will be caught by connrelease. Remember that 
the server earlier issued an l_SETSIG ioctl call to generate a signal on any 
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incoming event. Since the only possible Transport Interface events that can 
occur in this situation are a disconnect indication or orderly release indication, 
connrelease terminates normally when the orderly release indication arrives. 
The exit call in connrelease will close the transport endpoint, freeing the 
bound address for another user. If a user process wants to close a transport 
endpoint without exiting, it may call t_close. 

The Client 

The client's view of connection release is similar to that of the server. As men- 
tioned earlier, the client continues to process incoming data until t_rcv fails. If 
the server releases the connection (using either t_snddis or t_sndrel), 
t_rcv will fail and set t_errno to TLOOK. The client then processes the con- 
nection release as follows: 



if ((t^ermo — TLOCK) && (tJiOck(t6^ TjpBDREL)) { 
if {tjrcvreKfd) < of ( 

tjBrror(*tjrcvr«!l failed"); 
exit (6); 

if (t^sndrel (fd> < 0) t 

tjarror ( "t_^sndrel failed** ) ; 
elit(7); 

exit(O); 

tjBrror("t_rcv failed**); 
exit(a); 



When an event occurs on the client's transport endpoint, the client checks 
whether the expected orderly release indication has arrived. If so, it proceeds 
with the release procedures by calling t_rcvrel to process the indication and 
t_sndrel to inform the server that it is also ready to release the connection. 
At this point the client exits, closing its transport endpoint. 

Because not all transport providers support the orderly release facility just 
described, users may have to use the abortive release facility provided by 
t_snddis and t_rcvdis. However, steps must be taken by each user to 
prevent data loss. For example, a special byte pattern may be inserted in the 
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data stream to indicate the end of a conversation. There are many possible rou- 
tines for preventing data loss. Each application and high level protocol must 
choose an appropriate routine given the target protocol environment and 
requirements. 
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This section describes the connectionless-mode service of the Transport Inter- 
face. Connectionless-mode service is appropriate for short-term 
request/response interaction^, such as transaction processing applications. Data 
are transferred in self-contained units with no logical relationship required 
among multiple units. 

The connectionless-mode services will be described using a transaction server as 
an example. This server waits for incoming transaction queries, and processes 
and responds to each query. 

Local Management 

Just as with connection-mode service, the transport users must do appropriate 
local management steps before transferring data. A user must choose the 
appropriate connectionless service provider using t_open and establish its 
identity using t_bind. 

t_optmgmt may be used to negotiate protocol options associated with the 
transfer of each data unit. As with the connection-mode service, each transport 
provider specifies the options, if any, that it supports. Option negotiation is 
therefore a protocol-specific activity. 

In the example, the definitions and local management calls needed by the tran- 
saction server are as follows: 
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♦include <:Bt<lio.h> 
♦include <fdntl.h> 
♦include <tiuaer,h> 

♦clefine SRVADDR t 3^::ver'9 well known address *t 

m&in() 

lllllllllllllllllllllll 
tnt fd; 
int flags; 



Struct tj>ind *bind; 
struct tjunitdata *ud; 
Struct tjuderr *uderr; 

extern int t_errno; 



if {(fd • t_open('»/dev/tidg'^, 0_RDWR, NULL)) < 0) { 
t_jerror<**unaJ)le to open /dev/provider**) ; 
exit (1) ; 



if (<bind * (struct tj)ind *)t_alloc(fd, 
T_BIND, TJMm>> --TijULL) { 

tjerror<**tjilloc of tjbind atructuise failed") ; 
e«it(2); 



bind->addr^len *« slzeof(int); 
*(int *>bind->addr,buf - SBVJum; 
bind-Xjlen 0? ^ 

if (tj>ind(fd, bind, bind) < 0) { 
tjerrorCtJsind failed"); 
eJitO); 

* is the bound address correct? 



if (*(int *)bind->addr.buf J- SRV_ADDR) { 

fprintf <stderr, '^Jjind bound wrong addressVn"); 
exit (4); 
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The local management steps should look familiar by now. The server estab- 
lishes a transport endpoint with the desired transport provider using t_open. 
Each provider has an associated service type, so the user may choose a particu- 
lar service by opening the appropriate transport provider file. This 
connectionless-mode server ignores the characteristics of the provider returned 
by t_open in the same way as the users in the connection-mode example, by 
setting the third argument to NULL. For simplicity, the transaction server 
assumes the transport provider has the following characteristics: 

■ The transport address is an integer value that uniquely identifies each 
user. 

■ The transport provider supf)orts the T_CLTS service type (connectionless 
transport service, or datagram). 

■ The transport provider does not support any protocol-specific options. 

The connectionless server also binds a transport address to the endpoint so that 
potential clients may identify and access the server. A t__bind structure is allo- 
cated using t_alloc and the buf and len fields of the address are set accord- 
ingly. 

One important difference between the connection-mode server and this 
connectionless-mode server is that the qlen field of the t_bind structure has 
no meaning for connectionless-mode service, since all users are capable of 
receiving datagrams once they have bound an address. The Transport Interface 
defines an inherent client-server relationship between two users while establish- 
ing a transport connection in the connection-mode service. However, no such 
relationship exists in the connectionless-mode service. It is the context of this 
example, not the Transport Interface, that defines one user as a server and 
another as a client. 

Because the address of the server is known by all potential clients, the server 
checks the bound address returned by t__bind to ensure it is correct. 
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Data Transfer 

Once a user has bound an address to the transport endpoint, datagrams may be 
sent or received over that endpoint. Each outgoing message is accompanied by 
the address of the destination user. In addition, the Transport Interface enables 
a user to specify protocol options that should be associated with the transfer of 
the data unit (for example, transit delay). As discussed earlier, each transport 
provider defines the set of options, if any, that may accompany a datagram. 
When the datagram is passed to the destination user, the associated protocol 
options may be returned as well. 

The following sequence of calls illustrates the data transfer phase of the 
connectionless-mode server: 



if ((ud * (struct tjtmitdata *)t^alloc(£d, 
TJCJHITDATA, TJRLlT) NUU.) C 

t_error(**tj9XXoc of tjanltdata atnKJtu3?e failed**); 
exit(5>; 



if ((uderr » (struct t__uderr *)t_anoc(fd, 

tjBrzor(**t^alloc of tjudexr structure failed**); 
^t(«); 



while (1) { 

if (t_rcvudata(fd, ud, fiflags) < 0) { 
if (t ermo TLOOK) { 



* &rror on previously sent datagram 



if (t rcvuderj:(fd, wfejx) < 0) { 

exitm; 

fprintf (atderr^ **bad dat^ram, ^rlcot « %d\ti'*, 
^ider3>>eirror)[ t 

continue; 



} 

t error (*'t rcvudata failed**); 



(continued on next page ) 
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* QaeryO processes the zequest arx) pla<ses the 

* response in iiar'>udiit«.)>ufi^ sett^ vd*>q<totiiaen 

quexyOad}; 

if (t_sn<iu(3ata<f<i, na, 0) < 0> { 

tjB«ror(*t_sndudata failed**)? 



exitO) ; 



<3uety{) 



J 



/* Mfetely a stub for simplicity */ 



The server must first allocate a t_unitdata structure for storing datagrams, 
which has the following format: 









struct 


. tjanitdata 






sttuct netbuf addr; 




struct netbuf opt; 


llllll 


stmct netbuf ucUita; 









addr holds the source address of incoming datagrams and the destination 
address of outgoing datagrams, opt identifies any protocol options associated 
with the transfer of the datagram, and udata holds the data itself. The addr, 
opt, and udata fields must all be allocated with buffers large enough to hold 
any possible incoming values. As described in the previous section, the T_ALL 
argument to t^alloc will ensure this and will set the maxlen field of each 
netbuf structure accordingly. Because the provider does not support protocol 
options in this example, no options buffer will be allocated, and maxlen will be 
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set to zero in the netbuf structure for options. The server also allocates a 
t__uderr structure for processing any datagram errors, as discussed later in this 
section. 

The transaction server loops forever, receiving queries, processing the queries, 
and responding to the clients. It first calls t_rcvudata to receive the next 
query. t_rcvudata will retrieve the next available incoming datagram. If 
none is currently available, t_rcvudata will block, waiting for a datagram to 
arrive. The second argument of t_rcvudata identifies the t_unitdata struc- 
ture in which the datagram should be stored. 

The third argument, flags , must point to an integer variable and may be set to 
T_MORE on return from t_rcvudata to specify that the user's udata buffer 
was not large enough to store the full datagram. In this case, subsequent calls 
to t_rcvudata will retrieve the remainder of the datagram. Because t_alloc 
allocates a udata buffer large enough to store the maximum datagram size, the 
transaction server does not have to check the value of flags. 

If a datagram is received successfully, the transaction server calls the query 
routine to process the request. This routine will store the response in the struc- 
ture pointed to by ud, and will set ud~>udata . len to specify the number of 
bytes in the response. The source address returned by t_rcvudata in 
ud->addr will be used as the destination address by t_sndudata. 

When the response is ready, t_sndudata is called to return the response to the 
client. The Transport Interface prevents a user from flooding the transport pro- 
vider with datagrams using the same flow control mechanism described for the 
connection-mode service. In such cases, t_sndudata will block until the flow 
control is relieved, and will then resume its operation. 

Datagram Errors 

If the transport provider cannot process a datagram that was passed to it by 
t_sndudata, it will return a unit data error event, T_UDERR, to the user. This 
event includes the destination address and options associated with the 
datagram, plus a protocol-specific error value that describes what may be wrong 
with the datagram. The reason a datagram could not be processed is 
protocol-specific. One reason may be that the transport provider could not 
interpret the destination address or options. Each transport protocol is expected 
to specify all reasons why it is unable to process a datagram. 
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The unit data error indication is not necessarily intended to indicate success 
or failure in delivering the datagram to the specified destination. The tran- 
sport protocol decides how the indication will be used. Remember, the con- 
nectionless service does not guarantee reliable delivery of data. 

The transaction server will be notified of this error event when it attempts to 
receive another datagram. In this case, t_rcvudata will fail, setting t_errno 
to TLOOK. If TLOOK is set, the only possible event is T_UDERR, so the server 
calls t_rcvuderr to retrieve the event. The second argument to t_rcvuderr 
is the t_uderr structure that was allocated earlier. This structure is filled in by 
t_rcvuderr and has the following format: 



struct tjuderr { 

3truct neU>uf addb:; 
::»t3M3ct: netbuf Opt; 



where addr and opt identify the destination address and protocol options as 
specified in the bad datagram, and error is a protocol-specific error code that 
specifies why the provider could not process the datagram. The transaction 
server prints the error code and then continues by entering the processing loop 
again. 
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A user may wish to establish a transport connection and then exec (2) an exist- 
ing user program such as cat(l) to process the data as it arrives over the con- 
nection. However, existing programs use read(2) and write (2) for their 
input/ output needs. The Transport Interface does not directly support a 
read/write interface to a transport provider, but one is available with UNIX Sys- 
tem V. This interface enables a user to issue read and write calls over a tran- 
sport connection that is in the data transfer phase. This section describes the 
read/write interface to the connection-mode service of the Transport Interface. 
This interface is not available with the connectionless-mode service. 

The read/write interface is presented using the client example of the "Introduc- 
tion to Connection-Mode Service" section with some minor modifications. The 
clients are identical until the data transfer phase is reached. At that point, this 
client will use the read/write interface and cat(l) to process incoming data, 
cat can be run without change over the transport connection. Only the differ- 
ences between this client and that of the example in the "Introduction to 
Connection-Mode Service" section are shown below. 








Ilnclude <stroipt9fh> 






k * Same local nanagom^ 


It 


and; connectloai 





if (ioctKfd, I_PU5H, 'Miirdwr") < 0) { 

^xcmiTljmk Of tlrdwr Called*); 
e3cit(S); 

^iiiiliiillilillliiiliiiii^ 



^□S6dlt**Ai*r/bi»L/06t*', ♦»/ilsr/bln/cat«, 0) ; 
perrDr("eaBec?l of /usr/bln/cat failed"); 

V ^ J 

The client invokes the read/ write interface by pushing the tirdwr(7) module 
onto the Stream associated with the transport endpoint where the connection 
was established (see I_PUSH in streamio(5)). Tlds module converts the Tran- 
sport Interface above the transport provider into a pure read/write interface. 
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With the module in place, the client calls close (2) and dup(2) to establish the 
transport endpoint as its standard input file, and uses /usr/bin/cat to pro- 
cess the input. Because the transport endpoint identifier is a file descriptor, the 
facility for duping the endpoint is available to users. 

Because the Transport Interface uses STREAMS, the facilities of this character 
input/output mechanism can be used to provide enhanced user services. By 
pushing the tirdwr module above the transport provider, the user's interface is 
effectively changed. The semantics of read and write must be followed, and 
message boundaries will not be preserved. 

TThe tirdwr module may only be pushed onto a Stream when the tran- 
sport endpoint is in the data transfer phase. Once the module is pushed, 
the user may not call any Transport Interface routines. If a Transport 
Interface routine is invoked, tirdwr will generate a fatal protocol error, 
EPROTO, on that Stream, rendering it unusable. Furthermore, if the user 
pops the tirdwr module off the Stream (see i_P0P in streamio(5)), 
the transport connection will be aborted. 

The exact semantics of write, read, and close using tirdwr are described 
below. To summarize, tirdwr enables a user to send and receive data over a 
transport connection using read and write. This module will translate all 
Transport Interface indications into the appropriate actions. The connection can 
be released with the close system call. 

write 

The user may transmit data over the transport connection using write . The 
tirdwr module will pass data through to the transport provider. However, if 
a user attempts to send a zero-length data packet, which the STREAMS mechan- 
ism allows, tirdwr will discard the message. If the transport connection is 
aborted (for example, because the remote user aborts the connection using 
t^snddis), a STREAMS hangup condition will be generated on that Stream, and 
further write calls will fail and set errno to ENXIO. The user can still retrieve 
any available data after a hangup. 
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read 

read may be used to retrieve data that has arrived over the transport connec- 
tion. The tirdwr module will pass data through to the user from the transport 
provider. However, any other event or indication passed to the user from the 
provider will be processed by tirdwr as follows: 

■ read cannot process expedited data because it cannot distinguish 
expedited data from normal data for the user. If an expedited data indi- 
cation is received, tirdwr will generate a fatal protocol error, EPROTO, 
on that Stream. This error causes further system calls to fail. You should 
therefore not communicate with a process that is sending expedited data. 

■ If an abortive disconnect indication is received, tirdwr will discard it 
and generate a STREAMS hangup condition on that Stream. Subsequent 
read calls will retrieve any remaining data, and then read will return 
zero for all further calls (indicating end-of-file). 

■ If an orderly release indication is received, tirdwr will discard the indi- 
cation and deliver a zero-length STREAMS message to the user. As 
described in read (2), this notifies the user of end-of-file by returning 0. 

■ If any other Transport Interface indication is received, tirdwr generates a 
fatal protocol error, EPROTO, on that Stream. This causes further system 
calls to fail. If a user pushes tirdwr onto a Stream after the connection 
has been established, no indication will be generated. 



close 

With tirdwr on a Stream, the user can send and receive data over a transport 
connection for the duration of that connection. Either user may terminate the 
connection by closing the file descriptor associated with the transport endpoint 
or by popping the tirdwr module off the Stream. In either case, tirdwr will 
take the following actions: 

■ If an orderly release indication was previously received by tirdwr, an 
orderly release request will be passed to the transport provider to com- 
plete tihe orderly release of the connection. The remote user who initiated 
the orderly release procedure will receive the expected indication when 
data transfer completes. 



Transport Interface Programming 



2-49 



A Read/Wrtte Interface 



■ If a disconnect indication was previously received by tirdwr, no special 
action is taken. 

■ If neither an orderly release indication nor disconnect indication previ- 
ously received by tirdwr, a disconnect request will be passed to the tran- 
sport provider to abort the connection. 

■ If an error previously occurred on the Stream and a disconnect indication 
has not been received by tirdwr, a disconnect request will be passed to 
the transport provider. 

A process may not initiate an orderly release after tirdwr is pushed onto a 
Stream, but tirdwr will handle an orderly release properly if it is initiated by 
the user on the other side of a transport connection. If the client in this section 
is communicating with the server program in the "Introduction to Connection- 
Mode Service" section, that server will terminate the transfer of data with an 
orderly release request. The server then waits for the corresponding indication 
from ti\e client. At that point, the client exits and the transport endpoint is 
closed. As explained in the first list item above, when the file descriptor is 
closed, tirdwr will initiate the orderly release request from the client's side of 
the connection. This will generate the indication that the server is expecting, 
and the connection will be released properly. 
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This section presents the following important concepts of the Transport Interface 
that have not been covered in the previous section: 

■ an optional non-blocking (asynchronous) mode for some library calls 

■ an advanced programming example that defines a server supporting mul- 
tiple outstanding connect indications and operating in an event driven 
manner 



Asynchronous Execution Mode 

Many Transport Interface library routines may block waiting for an incoming 
event or the relaxation of flow control. However, some time-critical applications 
should not block for any reason. Similarly, an application may wish to do local 
processing while waiting for some asynchronous transport interface event. 

Support for asynchronous processing of Transport Interface events is available 
to applications using a combination of the STREAMS asynchronous features and 
the non-blocking mode of the Transport Interface library routines. Earlier exam- 
ples in this guide have illustrated the use of the poll system call and the 
I_SETSIG ioctl command for processing events asynchronously. 

In addition, each Transport Interface routines that may block waiting for some 
event can be run in a special non-blocking mode. For example, t_listen will 
normally block, waiting for a connect indication. However, a server can period- 
ically poll a transport endpoint for existing connect indications by calling 
t_listen in the non-blocking (or asynchronous) mode. The asynchronous 
mode is enabled by setting 0_NDELAY or 0_NONBLOCK on the file descriptor. 
These can be set as a flag on t_open, or by calling f cntl(2) before calling the 
Transport Interface routine, fcntl can be used to enable or disable this mode 
at any time. All programming examples in this chapter use the default synchro- 
nous processing mode. 

O^NDELAY or 0_NONBLC)CK affect each Transport Interface routine differently. 
To determine the exact semantics of 0_NDELAY or 0_NONBLOCK for a particular 
routine, see the relevant pages in Appendix A of this document. 
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Advanced Programming Example 

The following example demonstrates two important concepts. The first is a 
server's ability to manage multiple outstanding connect indications. The second 
is an illustration of the ability to write event-driven software using the Tran- 
sport Interface and the STREAMS system call interface. 

The server example in the "Introduction to Connection-Mode Service" section is 
capable of supporting only one outstanding connect indication, but the Tran- 
sport Interface supports the ability to manage multiple outstanding connect 
indications. One reason a server might wish to receive several simultaneous 
connect indications is to impose a priority scheme on each client. A server may 
retrieve several connect indications, and then accept them in an order based on 
a priority associated with each client. A second reason for handling several out- 
standing connect indications is that the single-threaded scheme has some limita- 
tions. Depending on the implementation of the transport provider, it is possible 
that while the server is processing the current connect indication, other clients 
will find it busy. If, however, multiple connect indications can be processed 
simultaneously, the server will be found to be busy only if the maximum 
allowed number of clients attempt to call the server simultaneously. 

The server example is event-driven: the process polls a transport endpoint for 
incoming Transport Interface events, and then takes the appropriate actions for 
the current event. The example demonstrates the ability to poll multiple tran- 
sport endpoints for incoming events. 

The definitions and local management functions needed by this example are 
similar to those of the server example in the section 'Introduction to 
Connectionless-Mode Service." 
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#incXt>de <tlti5er.h> 
llneludd <£cAtl.h> 

lincludd <ipoXX.h> 
llnclud^ <9tEopt8«h> 
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Icl^f liV9 HQMFDS 

Int connjCd; 



adrv^r^d w^XX kxlOMl ddlntos 
/♦ server xjotmectlon hw» */ 



/-* hoXda esGKmdct iiidlcatloni ♦/ 



Struct poXX^d p<>XlfdslNtMJPDSJ? 
Struct tjaind *blnd; 



main 


0 


{ 





iiiii™^^ 

* OnXy cpehln^ and binding otie transpcurt endpolnt^ 

* bat more could be supported 

if {(poXXfds{0].fd m tjat^ttCVtifev/tlvc** 
OjaDIR« NULL)) < 0) T 

t erKort"t; opea faiXed"); 

if (<bind - (struct tjaind *>t_aXXoG(poXlfdst01 .fd^ 
T_BIND, TALL) ) ^ TOiLy { 

tj6rror<*tjs»XXoc of tj>ind structure falXed*); 

bitjd-^>qXen - M^j3C»iNjdtt^ 
}9ind^>addr«len. •» sizeof(int>; 
*{int *)bind->addr.buf * smjsm: 



if (tJ>ind(poXlfdst01,fd* bind, bind) < 0) \ 
t error(^t bind faiXed*) ; 



exit (3); 



(continued on next page ) 
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♦ Kei9 the correct wldteeBR Jwund? 

iiiiiii^iiililliiillii 

it (*(int *)bind->addr.bu^ J- sRVADDR) { 

fptint£(9tderr, "t^bind bound wrong addressXn**) ; 

v 

The file descriptor returned by t_open is stored in a pollf d structure (see 
poll(2)) that polls the transport endpoint for incoming data. Notice that only 
one transport endpoint is established in this example. However, the remainder 
of the example is written to manage multiple transport endpoints. Several end- 
points could be supported with minor changes to the above code. 

An important aspect of this server is that it sets qlen to a value greater than 1 
for t__bind. This specifies that the server is willing to handle multiple out- 
standing connect indications. Remember that the earlier examples single- 
threaded the connect indications and resp)onses. The server would accept the 
current connect indication before retrieving additional connect indications. This 
example, however, can retrieve up to MAX_CONN_IND connect indications at one 
time before responding to any of them. The transport provider may negotiate 
the value of qlen downward if it cannot support MAX_CONN_IND outstanding 
connect indications. 

Once the server has bound its address and is ready to process incoming connect 
requests, it does the following: 



r 
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MtiXla (X) { 



for (1 0; i < NgMJD5; { 



default: 



perrorC^ppll rettumod error event 
exlt(€>; 



case 0: 



continue; 
case POtLIN: 



do_event (1. poilfds [1] .fd) ; 
;9er5rice_contt_ind (U pollfda [X} . f d) ; 



The events field of the pollfd structure is set to POLLIN, which will notify 
the server of any incoming Transport Interface events. The server then enters 
an infinite loop, in which it polls the transport endpoint(s) for events, and then 
processes those events as they occur. 

The poll call will block indefinitely, waiting for an incoming event. On return, 
each entry (corresponding to each transport endpoint) is checked for an existing 
event. If re vents is set to 0, no event has occurred on that endpoint. In this 
case, the server continues to the next transport endpoint. If revents is set to 
POLLIN, an event does exist on the endpoint. In this case, do_event is called 
to process the event. If revents contains any other value, an error must have 
occurred on the transport endpoint, and the server will exit. 

For each iteration of the loop, if any event is found on the transport endpoint, 
serviGe_conn_ind is called to process any outstanding connect indications. 
However, if another connect indication is pending, service_conn__ind will 
save the current connect indication and respond to it later. This routine will be 
explained shortly. 
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If an incoming event is discovered, the following routine is called to process it: 



( 



Airfltdi <t_look<f<i>> ( 
default ; 

fprlntf (stderr, "t^lopk: unexpected ev^t\ii") ; 
exlt(7>; 

case T_EPRDR: 

fpjtititf (dtderr^^t^looJc returned TJSRBQR evs^tXn^); 



case -*ai 



case 0; 



6xlt(8>; 



tjBrrorC't^looik failed"); 
exitW; 



/* since KttXIN xetumed, this Should not h«^^)en */ 
f printf (stdert, "t^look returned no eventNn**); 
ejtltdO); 



case TJLISTEKr: 



^ find free element in Calls array 

for (i - 0; 1< MWCjCmr^lND; i++> { 
if (calls [slotfilJ NOtt) 



l>reafc; 



if <{caiisEslotJ(i3 * ^struct t^call *)t_allQC<fd, 
TJUKLL, TJffiLH '^mtX.) t 

tjerrorCtjalloc of t j?all structure failed"^; 



«Kit(ll); 



if <t_Usten(fd^ callsfslotj U3> < 0) { 
tj©rror<«t^llsti$n failed*' J ? 
exita2); ^ 

break; 
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eadd tjDlSOOHHECTj 

discon - (struct tjJiaoon *)tjalXoc(fd*^ 

if (t_rcvdi9(f<l, dlBCon) < 0) \ 

tj6ttt>rC*tjcevdiA failed"^/ 

lilillllllllllll^ 

* find call ind In «rray and delete It 

for (1 0; 1 < Mlffa»N_I»D; !++> { 
if (dlscon«>sequence — 

calls [slot] ti]->sequenGe) { 

t_f ree <calls [ slot ] [ i ] , TCALL) ; 
calls [slot! [ij - mVL; 

t_f»ee<dlscony TJ>XS); 
break; 



) 




This routine takes a number, slot, and a file descriptor, fd, as arguments, 
slot is used as an index into the global array calls. This array contains an 
entry for each polled transport endpoint, where each entry consists of an array 
of t_call structures that hold incoming connect indications for that transport 
endpoint. The value of slot is used to identify the transport endpoint 

do__event calls t__look to determine the Transport Interface event that has 
occurred on the transport endpoint specified by f d. If a connect indication 
(T_LISTEN event) or disconnect indication (T_DISCONNECT event) has arrived, 
the event is processed. Otherwise, the server prints an appropriate error mes- 
sage and exits. 

For connect indications, do__event scans the array of outstanding connect indi- 
cations looking for the first free entry. A t_call structure is then allocated for 
that entry, and the connect indication is retrieved using t_listen. There must 
always be at least one free entry in the connect indication array, because the 
array is large enough to hold the maximum number of outstanding connect 
indications as negotiated by t_bind. The processing of the connect indication 
is deferred until later. 
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If a disconnect indication arrives, it must correspond to a previously received 
connect indication. This occurs if a dient attempts to undo a previous connect 
request. In this case, do_event allocates a t_discon structure to retrieve the 
relevant disconnect information. This structure has the following members: 

iliHlil^MBII^ 

stxtict tjdlacon { 

dtxuct netbuf tidats; 

. J 

where udata identifies any user data that might have been sent with the 
disconnect indication, reason contains a protocol-specific disconnect reason 
code, and sequencer identifies the outstanding connect indication that matches 
this disconnect indication. 

Next, t_rcvdis is called to retrieve the disconnect indication. The array of 
connect indications for slot is then scanned for one that contains a sequence 
number that matches the sequence number in the disconnect indication. 
When the connect indication is found, it is freed and the corresponding entry is 
set to NULL. 

As mentioned earlier, if any event is found on a transport endpoint, 
service_conn_ind is called to process all currently outstanding connect indi- 
cations associated with that endpoint as follows: 
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r 



"A 



isexvice conn lnd(5Xot, fd) 
{ 

int 1; 



fpr (1 



- 0; 

If 



1 < MMqj30NN_IND; i++) { 
(caXlsffllotHU — NOU,) 
continue; 



if <<conn fd t openC/d^v/tivc-, 0 RDMR^ NtlLL)) 
< 0) ^ 

t j&r«>rr<q?en faUed**); 

if ^tblnd<COnn_fd, NOEL, NtJli) < 0> { 
tjBrrorCtJjind failed")/ 
eJitaS); 



if (t_accept(fd, conn_fd. callatslot] {i]> < Q) ( 
if (t_0rmo^ ttOOK) ( 

t__close<conn_fd) ; 
netuxn; 

lllllllllllllllllll^ 

t j^rrorCtjaccept failed"); 
exit (16); 

t_free<callaIalot]liJ^ 7CALL); 
callsrslotjlij NOrX; ^ 

ruii_«erver<fd) ; 




For the given slot (the transport endpoint), the array of outstanding connect 
indications is scanned. For each indication, the server will open a responding 
transport endpoint, bind an address to the endpoint, and then accept the con- 
nection on that endpoint. If another event (connect indication or disconnect 
indication) arrives before the current indication is accepted, t__accept will fail 
and set t errno to TLOOK. 



Transport Interface Programming 



2-59 



I 

Advanced Topics | 



The user cannot accept an outstanding connect indication if any pending 
connect indication events or disconnect indication events exist on that tran- 
sport endpoint. 



If this error occurs, the responding transport endpoint is closed and 
service_conn_ind will return immediately (saving the current connect indi- 
cation for later processing). This causes the server's main processing loop to be 
entered, and the new event will be discovered by the next call to poll. In this 
way, multiple connect indications may be queued by the user. 

Eventually, all events will be processed, and service_conn_ind will be able 
to accept each connect indication in turn. Once the connection has been esta- 
bhshed, the run_server routine used by the server in the "Introduction to 
Connection-Mode Service" section is called to manage the data transfer. 
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These tables describe all state transitions associated with the Transport Interface. 
First, however, the states and events will be described. 

Transport Interface States 

Table 2-6 defines the states used to describe the Transport Interface state transi- 
tions. 



Table 2-6: States Describing Transport Interface State Transitions 



State 


Description 


bervice Type 


T_UNINIT 


uninitialized - initial and 
final state of interface 


T_COTS, 

T_COTS_ORD^ T_CLTS 


T_UNBND 


initialized but not bound 


T_COTS, 

T_COTS_ORD, T_CLTS 


T_IDLE 


no connection established 


T_COTS, 

T_COTS_ORD, T_CLTS 


T_OUTCON 


outgoing connection 
pending for client 


T_COTS, T_COTS_ORD 


T_INCON 


incoming connection 
pending for server 


T_COTS, T_COTS_ORD 


T_DATAXFER 


data transfer 


T_COTS, T_COTS_ORD 


T__OUTREL 


outgoing orderly release 
(waiting for orderly 
release indication) 


T_COTS_ORD 


T_INREL 


incoming orderly release 
(waiting to send orderly 
release request) 


T_COTS_ORD 
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Outgoing Events 

The outgoing events described in Table 2-7 correspond to the return of the 
specified transport routines, where these routines send a request or response to 
the transport provider. 

In the table, some events (such as accept N) are distinguished by the context in 
which they occur. The context is based on the values of the following variables: 

cent count of outstanding connect indications 

f d file descriptor of the current transport endpoint 

resf d file descriptor of the transport endpoint where a connection will 

be accepted 



Table 2-7: Outgoing Events 



Event 


Description 


Service Type 


opened 


successful return of t__open 


T_COTS, 

T_COTS_ORD, T_CLTS 


bind 


successful return of t_bind 


T_COTS, 

T_COTS_ORD, T__CLTS 


optmgmt 


successful return of t_optmgmt 


T_COTS, 

T_COTS_ORD, T__CLTS 


unbind 


successful return of t^unbind 


T_COTS, 

T_COTS_ORD, T_CLTS 


closed 


successful return of t_close 


T_COTS, 

T_COTS_ORD, T_CLTS 


connect 1 


successful return of t_connect in 
synchronous mode 


T_COTS, T__COTS_ORD 
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Table 2-7: Outgoing Events (continued ) 



Event 


Description 


Service Type 


connect 2 


TNODATA error on t_connect in 
asynchronous mode, or TLOOK error 
due to a disconnect indication arriv- 

11 SJll tl l\Z llCUI9LAJli dlVlL/V/llll 


T_COTS, T_COTS_ORD 


accept 1 


successful return of t__accept with 
cent == 1, fd == resfd 


T__COT5 f T_COT5__ORD 


accept2 


successful return of t_accept with 
ocnt = Ir fd != resfd 


T^COTS / T_COTS_ORD 


accepts 


successful return of 
t_accept with ocnt > 1 


T_COTS , T_COTS_ORD 


snd 


successful return of t_snd 


T_COTS, T_COTS__ORD 


snddisl 


successful return of 
t_snddis with ocnt <= 1 


T_COTS, T_COTS_ORD 


snddis2 


successful return of 
t_snddis with ocnt > 1 


T_COTS, T_COTS_ORD 


sndrel 


successful return of t_sndrel 


T__COTS_ORD 


sndudata 


successful return of t_sndudata 


T_CLTS 
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Incoming Events 

The incoming events correspond to the successful return of the specified rou- 
tines, where these routines retrieve data or event information from the transport 
provider. The only incoming event not associated directly with the return of a 
routine is pass_conn, which occurs when a user transfers a connection to 
another transport endpoint. This event occurs on the endpoint that is tfeihg 
passed the connection, despite the fact that no Transport Interface routine is 
issued on that endpoint. pass_conn is included in the state tables to describe 
the behavior when a user accepts a connection on another transport endpoint. 

In Table 2-8, the rcvdis events are distinguished by the context in which they 
occur. The context is based on the value of cent, which is the count of out- 
standing connect indications on the transport endpoint. 



Table 2-8: Incoming Events 



Incoming 
Event 


Description 


Service Type 


listen 


successful return of t_listen 


T_COTS, T_COTS_ORD 


rcvconnect 


successful return of t_rcvconnect 


T_COTS, T_COTS_ORD 


rev 


successful return of t_rcv 


T_COTS, T_COTS_ORD 


rcvdisl 


successful return of t_rcvdis 
with cent <= 0 


T_COTS, T_COTS_ORD 


rcvdis2 


successful return of t_rcvdis 
with cent == 1 


T_COTS, T_COTS_ORD 


rcvdis 3 


successful return of t_rcvdis 
with cent > 1 


T_COTS, T_COTS_ORD 


rcvrel 


successful return of t_rcvrel 


T_COTS_ORD 
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Table 2-8: Incoming Events (continued ) 



Incoming 
Event 


Description 


Service Type 


rcvudata 


successful return of t_rcvudata 


T_ 


_CLTS 


rcvuderr 


successful return of t_rcvuderr 


T_ 


_^CLTS 


pass_conn 


receive a passed connection 


T_ 


_^COTS, T_COTS_ORD 



Transport User Actions 

In the state tables that follow, some state transitions are accompanied by a list of 
actions the transport user must take. These actions are represented by the nota- 
tion [n], where n is the number of the specific action as described below. 

[1] Set the count of outstanding connect indications to zero. 

[2] Increment the count of outstanding connect indications. 

[3] Decrement the count of outstanding connect indications. 

[4] Pass a connection to another transport endpoint as indicated in 

t^accept. 



State Tables 

The following tables describe the Transport Interface state transitions. Given a 
current state and an event, the transition to the next state is shown, as well as 
any actions that must be taken by the transport user (indicated by [n]). The 
state is that of the transport provider as seen by the transport user. 

The contents of each box represent the next state, given the current state 
(column) and the current incoming or outgoing event (row). An empty box 
represents a state/event combination that is invalid. Along with the next state, 
each box may include an action list (as specified in the previous section). The 
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transport user must take the specific actions in the order specified in the state 
table. 

The following should be understood when studying the state tables: 

■ The t_close routine is referenced in the state tables (see closed event 
in Table 2-9), but may be called from any state to close a transport end- 
point. If t_close is called when a transport address is bound to an end- 
point, the address will be unbound. Also, if t_close is called when the 
transport connection is still active, the connection will be aborted. 

■ If a transport user issues a routine out of sequence, the transport provider 
will recognize this and the routine will fail, setting t_errno to TOUT- 
STATE. The state will not change. 

■ If any other transport error occurs, the state will not change unless expli- 
citly stated on the manual page for that routine. The exception to this is a 
TLCX)K or TNODATA error on t_connect, as described in Table 2-1. The 
state tables assume correct use of the Transport Interface. 

■ The support routines t_getinfo, t_getstate, t_alloc, t_f ree, 
t_sync, t_look, and t_error are excluded from the state tables 
because they do not affect the state. 

A separate table is shown for common local management steps, data transfer in 
connectionless-mode, and connection-establishment/connection-release/data- 
transfer in connection-mode. 
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Table 2-9: Common Local Management State Table 



state 
event^\^^ 


T_UNINIT 


T_UNBND 


T_IDLE 


opened 


T^UNBND 






bind 




T_IDLE [1] 




optmgmt 






T__IDLE 


unbind 






T_UNBND 


closed 




T_UNINIT 





Table 2-10: Connectionless-Mode State Table 



state 
event^s. 


T_IDLE 


sndudata 


T_IDLE 


rcvudata 


T_IDLE 


rcvuderr 


T_IDLE 



Transport Interface Programming 



2-67 



state Transitions 



Table 2-11: Connection-Mode State Table 



state 
event\. 


T_IDLE 


T_OUTOOH 


T_I1IC0N 


TJDATAXTER 


TjOUTREL 


T_IliREL 


connect 1 


T__DATAXPER 












connect 2 


T_ODTCON 












rcvconnect 




TJDATAXFER 










listen 


T_INCX>N [2] 




T_INCONr [2] 








accept 1 






TJDATAXFER [3] 








acc^t2 






T__IDLE [3] [4] 








accepts 






T_1HC0II [3] [4] 








and 








TJDATAXFER 




T^INREL 


rev 








TJJATAXFER 


TjOUTREL 




snddlsl 




T_IDLE 


T_IDLE [3] 


T_IDLE 


TjIDLE 


T_IDLE 


8nddl82 






T__INCON [3] 








rcvdlsl 




T_IDLE 




TjIDLE 


T_IDLE 


T_IDLE 


rcvdl82 






T_1DLE [3] 








rcvdl83 






T_IHCX»I [3] 








8ndrel 








TjOUTREL 




TjIDLE 


rcvrel 








TjINREL 


T_IDLE 




pa88__conn 


T_pATAXrER 
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By defining a set of services common to many transport protocols, the Transport 
Interface offers protocol independence for user software. However, not all tran- 
sport protocols support the services supported by the Transport Interface. If 
software must be run in a variety of protocol environments, only the common 
services should be accessed. The following guidelines highlight services that 
may not be common to all transport protocols. 

■ In the connection-mode service, the concept of a transport service data 
unit (TSDU) may not be supported by all transport providers. The user 
should n\ake no assumptions about the preservation of logical data boun- 
daries across a connection. If messages must be transferred over a con- 
nection, a protocol should be implemented above the Transport Interface 
to support message boundaries. 

■ Protocol and implementation specific service limits are returned by the 
t^open and t_getinf o routines. These limits are useful when allocat- 
ing buffers to store protocol-specific transport addresses and options. It is 
the responsibility of the user to access these limits and then adhere to the 
limits throughout the communication process. 

■ User data should not be transmitted with connect requests or disconnect 
requests (see t_connect(3N) and t_snddis(3N)). Not all transport pro- 
tocols support this capability. 

■ The buffers in the t_call structure used for t_listen must be large 
enough to hold any information passed by the client during connection 
establishment. The server should use the T_ALL argument to t_alloc, 
which determines the maximum buffer sizes needed to store the address, 
options, and user data for the current transport provider. 

■ The user program should not look at or change options that are associated 
with any Transport Interface routine. These options are specific to the 
underlying transport protocol. The user should not pass options with 
t_connect or t__sndudata. In such cases, the transport provider will 
use default values. Also, a server should use the options returned by 
t_listen when accepting a connection. 

■ Protocol-specific addressing issues should be hidden from the user pro- 
gram. A client should not specify any protocol address on t_bind, but 
instead should allow the transport provider to assign an appropriate 
address to the transport endpoint. Similarly, a server should retrieve its 
address for t_bind in such a way that it does not require knowledge of 
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the transport provider's address space. Such addresses should not be 
hard-coded into a program. A name server procedure could be useful in 
this situation, but the details for providing this service are outside the 
scope of the Transport Interface. Etetailed information about Network 
Selection and Name-to-Address Mapping can be found in the "Network 
Selection and Name-to-Address Mapping" chapter. 

■ The reason codes associated with t_rcvdis are protocol-dependent. The 
user should not interpret this information if protocol-independence is 
important. 

■ The error codes associated with t_rcvuderr are protocol-dependent. 
The user should not interpret this information if protocol-independence is 

a concern. 

■ The names of devices should not be hard-coded into programs, because 
the device node identifies a particular transport provider, and is not pro- 
tocol independent. 

■ The optional orderly release facility of the connection-mode service (pro- 
vided by t_sndrel and t_rcvrel) should not be used by programs tar- 
geted for multiple protocol environments. This facility is not supported 
by all connection-based transf>ort protocols. In particular, its use will 
prevent programs from successfully communicating with ISO open sys- 
tems. 
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The examples presented throughout this guide are shown in their entirety in 
this section. 



Connection-Mode Client 

The following code represents the connection-mode client program described in 
the section 'Introduction to Connection-Mode Service." This client establishes a 
transport connection with a server, and then receives data from the server and 
writes it to its standard output. The connection is released using the orderly 
release facility of the Transport Interface. This client communicates with each of 
the connection-mode servers presented in the guide. 



liiiclude <stdid.h> 
#inclt>cJe <tlu»er,h> 
#lneau<ite <f<2ntl.h> 

#d0f Ine SRV ADDR a 



/♦ aerver'a well known acfcireas */ 



mai]i( ) 
f 



Int fd; 

Int libytes; 

ittt fXaga ^ 0; 

char buf [1024]; 

atracst tjsail *3ndca3.1; 



if (<fd - t_<^(**/d(6v/tivc*, ojccm, mm) < o) { 

tjsrror{"tjDpen failed"); 
eatit(l); ^ 

iiiiiiiiliiiiiiiiiiiiiiiii^ 

if (tj?ii«5(fd, NTO.. NOLI.) < 0^ { 
tjBri6r<^tbiftd failed") ; 
exit (2); 

* By «5sund,ng that the add^esd id an integer vaXtae, 

* thi? program may not run pver another protocol. 
*/ 
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if ((andcaXl - <dtract tjcsau *)talXoc(«d, 

TjaLL, tADDR)> NoEt,) ( 

t^errorC't^^Uoc failed**); 
exit (3); 

iiiiiiiiiiiiiiiiiiiiiii 

^<int *)andcall->iKJdr.buf • ^JiX>m 

if (t_pow)ect(fd, sndcaXX, HOIX) < 0) { 

^ tjBtEorit^tj«aaw<± f^iX^ for fd**); 
eaat(4>; 

iiiiiiiiiiiiiliiiiiiiiiiiii^^ 

. ^IXe ((nbytea - tjpcv(fa* buf, XC24, 4flag3>> !- -X) { 
if <£writ«(buf, 1, nbytea, atdout) < 0) ( 

fprintf (stderr, »»fwrite faiXedXn"); 
exit (5); 

if <(t_ermo — TLOOK> £S (t^Xook{fd> — TORMIELH ( 
if (t_rcvrel(f<J) < of J 

tjerror ( " t^rcvrel f aiXed** ) ; 
OTit(6); 

If <t_»ftdxBX(fd) < 0) ( 

tjerpor("t;^3ndreX failed"); 
^it(7)? 

iiiiiiiiiiiiliiiiiiii;! 

exit(O); 

iiiiiiiiiiiiiiiiiiiiiiiiiiii^^^ 

tjerror ("t^rcv failed*'); 
exit<a); ^ 
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Connection-Mode Server 

The following code represents the connection-mode server program described in 
the "Introduction to Connection-Mode Service" section. This server establishes 
a transport connection with a client, and then transfers a log file to the client on 
the other side of the connection. The connection is released using the orderly 
release facility of the Transport Interface. The connection-mode client presented 
earlier will communicate with this server. 



fincludd <tlDd6r.h> 
llnclucte <3trQpt9.i>> 

lineli^ <stdid.h> 
^include <si9iial«h> 

#def ine DI3C0NNBCT -1 
#dfef Ine SRVADDR 1 

int connjfd; 
extern int t ermo; 



/* dertrer'5 wfelX knoxn address */ 

/* connection established heape */ 



/* listening taSandpOrt end|)oint */ 



int listenjtd; 

:: Struct :t;^j5ind: *bind;;^;^:^::: 

struct tcaia *call; 

if ((listen^fd - tJ>penr/dev/tivc^ OWm, mJIX>> 
< 0) { " 

tjerxor<«tjppeii faiied tox: Xisten^fd*>; 
e*it(l)> " 

* jdy assundng that th^ addles is an integ«»r vaXue^ 

* this pto^tam may not run over another protocol. 

it ((bind - (strtict t_bind *>t_alloc(listen_fd, 

T^BIND, T_ALL)) ^ NULL) { 

t^errorC't^alXoc of t_bind structure failed"); 

bind-xjien ^ 1; 
bind->addr,l^ si^eof (int); 
*(int *)bind->addr,buf - SRV_ADDRa 

if (t bind (listen fd/ bind, bind) < 0) { 
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t^&xxoti**tJ>itid failed for Xistenjrd*) ; 

llllllllll 

Wa3 the tott^t address bound? 

iiliiii^iiliiiiiiiiiiiiiiii;^^ 

if (*(int *)bind->dddr.buf t-^ SRVADDR) { 

fpHnt£<stdarr, ^tj>ix^ h&Ojad it£6ln^ «iidatoed Ati**) ; 

lllillllliiiiilllllli^ 

if ((caxa m (struct tjsaXX *)t_aXXoc<li«tenfd,h 

tjewrorC^aiXoc of t caXX atructure failed"); 

iiiii^i^iiiiiiililB^ 

%*hiXe (X) I 

If (t_Xistea<Xisten_fd, caXX> < 0> ^ 

t_error("t_llstai failed for listari^f d") ; 
^it(€); 

If <(<50nnjfd - acc^t_call(listen_fd, call)) 
!« DIsdoNNECT) 

xm server<listen fd> ; 



J 



accept^caXX ( Xi»teii_f d, call) 
Int Xisten^fd; 
struct tjsall *call; 



int resfd; 

if ((resfd * t^cjpetir/dev/tlvc", OJttSWR, mt.» < 0) ( 
t error (*t lypm for responding fd failed"); 
esdtm; 

if <tj>ind<resfd, NULL, NOLL) < 0) { 

tj6rror(*tJbind for responding fd failed"); 
eJit(8); 

if (t^acc^tdlstenjPd^ re»fd* call) < O) { 

if (tj&rwS mm ruom) i /* mxst be a disc<»inect */ 
if ft;_rcvdls<listen_fd, NmL) < 0) { 

tjarror("t_rcvdi« failed for listen^fd"); 
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it CtclOBe(reafd) < 0) { 

tjM:xor(**tj5Xode faU«! for »&apc«idlng £d"); 

/* ^6 hddk. up a»d liatm t6t other calls */ 
z^tuzn (DI3CX)NMBCT} ; 

t_Grror<'*tjkc6apt failed**)! ; 



) 

r^tiixn (reaf d) ; 



connxeXeadeO 

iiiiiiiilliiiiiiiiiiiiiiiiiii 

/* conn^fd i3 global because needed here */ 
if (t_lSolc(cotm_fd) — tt)ISOOWIESCTj[ ( 

fprlntf (stderr, »*oonnection aborted\n«'> ; 

exit (12); 

/* else orderly release indication ^ nortnftX exit ^/ 

Ifllllllllllllllll^ 

run_server<listen^fd) 
int liaten^fd; 

int nbytei; 

FILE *^logfp; /* file pointer to log file */ 

char bttf [1024]; 

switdi (foritO) { 

case -li 

perror(^f0rk failed"); 
^it(20); 

default; /* parent */ 

/* close cotm_fd and then go up and list^ again */ 
if (t_elo3e(connjrd) < 0) { 

tjerrorCtjClose failed for conn_fd'*); 

exit (21); 

iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii^ 

return; 

case Or /♦ child V 
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/* cX08e llaterUTd ««i do service */ 
if <tj2X09e(XUtieinJKl) < 0) { 

t_j©rrpr("tJclose failed for llBten^fd") ; 

illiiiiiiliiiiliiilliiiiiiii 

if ((logfp « r<jpen("l<?gflle**r "r'^yj — NOLL) ( 
perxior( '^cannot open logfile**); 



exit (23); 



signal (SICP0I^« connTeXease) ; 

if iiocti(oomj:d, ijSBTSiG, sjmn) < o) ( 

periawr("ioctl IJSETJsS failecj") ; 
exit (24); 

) 

If (t_look (cann_fd) 1*» 0) ( /*" was clisqonnect there? */ 
f printf (stderr^ *t_Xo6lc: tweitpected event \n**); 
exit (25); 

||||||||||:||||||||| 

whiie ((nbytes - fread<buf, l, X024, Xogfp)) > 0) 
if (t_^snd(conn_fd, baf, nbytes, 0) < 0) { 
tjerror C*'t^snd faiXed"); 
exit (26); ^ 

lillllillillilliiiiil^ 

if (t_sndreX(«)nrl_fd) < 0) ( 

tjw:xor("t^3ndreX failed"); 
«tit(27); 

pauseO; /* wtii orderly release iiwJicaticn aurrives */ 
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Connectionless-Mode Transaction Server 

The following code represents the connectionless-mode transaction server pro- 
gram described in the section "Introduction to Connectionless-Mode Service/' 
This server waits for incoming datagram queries, and then processes each query 
and sends a response. 

♦include <aitdio.h> 
linqlude <fQn!tl^h> 
♦include <tiuww:,b> 

#diafin0 3RVADDR ^ server's well known addr*es3 

ittt J5d; 
int flags; 

Struct tj>ln<j *l>ind; 
stiiict tJJnltdata *ud; 
5tx?act tjunferr *uclerr; 
extetn Int t erxno; 



if <<fd t_OE>^(Vdev/tidg*, OJRDWR, MOIX)) < 0> 
t^erxor ("unable to open /dev/prov±dBr'»> ; 
exit (l> ; 



if ((bind - (attuct tj&ind *>t_alloc(fd, 

TJ3IND, tADDR)) — TnOII.^ ( 

tjeri:or(**tjiUoc of tbind structure failed"); 
€5cit(2); ^ 

bind->add?raen * si^peof (int>; 

l^ind'T^qlen • Of 

if (tbind(fd, bind, bind^ < 0) { 
t©jrror<'*tJ>ind failed*)! t 
^it(3); 







* U the bound 


addxe9s corzBct? 
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fprintf (stderi^, '*tj>lnd bound Wrdng lK3dx0Ss\zl**) ; 



exit(4>; 



TJDNITDAIEA, StAtit,)) — «0!LL)[ ( 

t:j9rror("tjallpQ p£ tLjtmitdata 9tmctuxe faiifld**); 
exit(5>/ 

If ((ucterr - (struct tu<Jerr *)t_aiioc(fa. 



e«it<6>; 



> 



^1X& (1) J 

if (t_^rcvadata(fd, ud, fifla^i) < C) { 
if (t erxvo — !rLOOK> { 



^ Error on previously sent datagraro 

|||||||||||;|;|:::|^^ 

if <tjrcsvuderr(fd, udarr) < 0) { 

t_error ( " t_^rcvuderr f ai led" ) ; 
exit (7); 

fprintf (stderjT, "bad datagram^ 
etxot - MVn", aderr-*>error> ; 
continue; 

t jettor ( "t^rcvudata failed" ) ; 
exit (8); " 

* Query (> processes the tiequest and places the 

* response in ud-^>udata,buf, setting ud^>udata.len 

query (ud) ; 

if <t_sndudata(fd, ud, 0) < 0) { 

tjarror("t_sndudata failed"); 
eiit(9); 
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iliiiiiiiliiiliiiilliiiiii 

/* MiareXy n stub for aiwpXleity V 

illiililiiiiiiiiiiiiiiiili 



Read/Write Client 

The following code represents the connection-mode read/ write client program 
described in the section "A Read/Write Interface/' This client establishes a tran- 
sport connection with a server, and then uses cat (1) to retrieve the data sent by 
the server and write it to its standard output. This client will communicate with 
each of the connection-mode servers presented in the guide. 
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lindude <tiud^.h> 
♦inclxKJe <fcntl,h> 
lincXtide <AtXQpta,h> 

#<Jef ine SBST ACW 3. 



/* aeirveir's mil known; «3di?es8 */ 



i 



int fd; 

lilt ^ 0; 
<;dMir buf (1024]; 
iitjticft t^call *5nacalX; 
dxtdxn. Int tjBrmo; 

If ({fd - t_open(Vd6v/tivc**, 0_wm, NUU.>> < 0> { 
tjerrort^tjopen failed'*); 
exit(l>; 

if (t_bind<fd> NOLL, TOJ.) < 0) ( 
^ tjerror('*tJ>ind fiildd^); 
eatit(2>; 

iiiiiiiiiillii^iiiiii^iil^ii 

* By adduming that the 4ddxea« U an int^r V4!,lu^^ 

* thia program may not run Qvpr another protQCJOl > 



if «flindqaii - {struct t_jcall *)t_alloc<fd, 

t3a^s^(*tjilloc failed**); 
€«it(3); 

iiillllliliii 

andoall->addr,len - aizeofCint); 
*(int *)3ndcall->addr.buLf - SRV_AM)R; 

if {t_cow^t(fd, dttdcaU, NCDX) < 0) { 

tjBrEbr{'*t_cOnneet faiXdd £o£ fd**); 
«^it(4); 

liiiijiililliii 
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If (ioctim, XJ?VSHr "tltdwr") < 0) { 

terror ("1_P0SH of titdwt failed"); 
exit (5); 

cXo5e<0^ ; 
<*^(fd>; 

^dfiocxr/usr/bin/cat^^ Vudr/bin/caf*, 0); 



peyyQr(" e »»qi of /usr/bin/cat failed"); 
exit (6); 



Event-Driven Server 

The following code represents the connection-mode server program described in 
the section "Advanced Topics/' This server manages multiple connect indica- 
tions in an event-driven manner. Either connection-mode client presented ear- 
lier will communicate with this server. 
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#incXud6 <tluaer.h> 
#lnelud6 <fcaitl,h> 
#incli3Cte <3t<3io.h> 
#lttcXtid(e <j»XXah> 

Icjb^f ine WJtiFDS 

§6i&£itiA mcjxm xm 
int cormjfd/ 



/* server cxamection */ 



/* hblds Cxtoiiect Indications */ 

struct t^caXl ♦calXs tNUMJTJSJ [MKXJXXOSljrSD) ; 

iiiiiiiiiiiiiiliiiiiiiiiiiiii 

stn^et j»Xl£d poXlfdsf{liOMJ?t)^],* 
struct t_bin4 *bind; 
int it 



* Only opening and binding one transport en<^int^ 
^ but more couXd be supported 

it ((polXfdsroj,fd t_open(*/dev/tlvc-, OJixm, WXIs)) 
< 0) { 

tjerrorC't.open failed**); 
exlt(X>; 



it ((bind* (struct tj>ind *)t_alloG(polXfdsJO) ,fd, 
T_BIND, T_AU,>> ^ HJLL) { 

tj6rror(**t_alloc of t_blnd structtire failed*); 
e3d.t(2>; ^ 

blnd->qlen » IjAXjOONNJEND? 
binch>addr. len - slzeof (int); 
*(lnt ♦)[blnd->dddr.buf - SftVjUim; 

it (tJ>lnd(pollfds[OJ.fd. bind* bind) < 0) { 
tj6rror(*tJbind failed*); 
eSdtO); 
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f ^ 

* w«9 the correct **S3t»»» bowKJ"? 

iiiiiiiiiiiiiiiilililiiii^^^^^ 

fprlnt;e(9t<3BXrr "tJblJKi bownd wong ^^^WJWsVn") ; 
«tit(4)i 

iiiiiiiiiiiiiiiiiiilB^^^^ 

. . uhlXe (1) { 

it (polKppllfdSr HOMJDB, -1) < 0> { 

perrorrpoU falXed"); 
BititiB); 

tor (i - 0; i < NUM_FDS; i++) { 

i¥ltd^ (poXlfds[i3 .revetitd) { 
4efauXt: 

perror<'*poXX returned error event 
exit (6); 

case 0: 

continue; 



case POLLUS: 

dojawnta^ poXXf<to[iJ.fd>; 
36JviC»jc0na_ind {i, poXXfds (11 . f d) ; 

illiiillliii 



lllllliil 

<kL.event{9loti' td) 
I 



struct tjdiacon Miacon; 
Int i; ~ 



SWitcfc <t_X*)oki[fd)) { 
ddfauXt: 



f prlntf <stderr, •'t_lodcT unexpected event \n") ; 
exit (7); 
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cadd tJSI®OR: 



exit {8); 



case "1: 



<sase 0: 



/* 3lnoe POLLIN yetu^Tieci^ this »houW not lM^^>en */ 
fpritttf (dtderr,**tJLooIc retuttied no ev^ntXn**); 
exit (10); " 



* find ftee element in calls array 

for (i - 0; i < MMCjCSONH^JND; 1++) { 
if (calls tdlotjli: mm*) 
break; 



If < (calls [slot] (1] • (struct tjMll ^)t_anoc(£d, 
TJ»LL^ TAEL) ) — NOLL) 

tjerrorCtjalloc of t ^j»ll structure failed"); 



If (t^listen (fd, calls IslotHi}) < 0> ( 
t jerror ( ♦*t_llstett failed" ) ; 
€ait(12); 

iiiiiiiiiilliliii-iiii^ 

break; 

case TJ>ISCONNEC!T; 

dlscon • (stru<St tjdis<50n *)t_allOc(fd, 
TJ)IS, TALL); 

If (t^rcvdis (fd, discon) < 0) { 

t^errorCt^rcvdis failed"); 
exit (13); 
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* fiad CAll itid In array and ddl^td it 

for (1 ^ Qi t < v»xjxmjcmi ( 

if (dl9<X)n->^^^<?e — 
caUB(»3lot3 {i^-^aequenoe^ { 

Call3{9lQt][i] • NOLL; 
t^free(di30on^ TOIS); 



Beiviqa_conn__ind(5lot/ fd) 

llilliliiiiiiii^ 



int i; 

for (i • 0; i < MaXJ30NN_IllD; i++) { 
if (calls [slotHil — miU) 
^QntiAude; 

if (<CGnn_fd - tjopen(Vdev/tivc'», 

tj&xj»r(*op6n failed*); 
^it(14); 

if (tj>ind<c<»m_fd, mi,, NDIX) < 0) | 
tjBrror("tJ>ind failed"); 
e^it(15); ^ 

lillllllllliiilllll^ 

if (t_aceept(fd^ cojwifd, calXsUlotJ ri3> < { 
if (termo"^ tLQQK) | 

t^clo3e(conn_fd) ; 
return; 

t^error ( "t j accept failed*); 
€«ita6); 

t_f ree (caXXd fsXot] li] , T^CALL) ; 
c»ilatalOtJ{il *• NOLL^ 
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iliiliiliiiiiil 



/* oonxi^fid ±9 glpl^al Ipsoaus^ needed hex^ *f 
if (t„looJc(conn_«> — yjPT8C0NW CT ) ( 



) 



/* ei,«e owterXy *>ei^a0 iiidt<»tion - nomX exit */ 



runjjorver ( 1 1 ^^tenjf <J) 

liiiiiiiiiiiiiiiiiill 



int nl>3^e9; 

PXCJg nogfp; /* flXe pointer to log file */ 

char buf [10241; 

dwitai (foiricO) ( 



perrorC'fork failed** ][;^ 
exit (20); 



default; /* parent */ 

/♦ <sl6se tiatmj^d and th6n ^o up and listen again */ 
If <t_cloaeiconn_fd) < 0) ( 

t^errorrtjcslode^ failed for conn^fd**); 

€acit(21); 

iiiiiiiiiiiiliiiliiiiliiii^ 

return; 

case 0: /* dilld */ 

/* close llsten_fd and do service */ 
if <t_close(ltsten_fd) < Q) { 

tj8trror(**tjclose failed for listen^fd**) ; 

exit (22);"' 

it ((logfp - f open Clogf lie**, **r'*)) — * NULL) { 
perix>r( "cannot cpen logfile**); 
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exit (23); 

liiiiiiiiiiiiiiiiiiiiiiii;;!!^ 

if Uoctl (^..orm^fci, IJ^T$IG, S^INPUT) < 0) { 

liiillliiiilllllllig 

If <tJlook(corm_fd) i-'- 0) { /* dls<H»m6Ct already there? */ 
fprlAtiCdtdarr, **tJLd6k: Iltte3^)ected evBntXn**) ; 
e«it(25>; 

i*dl© <<nbyte5 * fread(buf. 1. X024, logfp)) > 0) 
if (t_snd (oonn_f d, buf, iibytes, 0) < 0) ( 
t__error<'»t_snd failed"); 
exit (26); 



if (t_andreX(conn_fd> < 0) { 

tjBriDr("t_sndrel failed**); 
e^it(27); ^ 

: : paUSe( ) ;: : : /*: :T^^ 
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The following terms apply to the Transport Interface: 
Abortive release 

An abrupt termination of a transport connection, which may 
result in the loss of data. 

Asynchronous execution 

The mode of execution in which Transport Interface routines 
will never block while waiting for specific asynchronous events 
to occur, but instead will return immediately if the event is not 
pending. 

Client The transport user in connection-mode that requests a transport 

connection. 

Connection establishment 

The phase in connection-mode that enables two transport users 
to create a transport connection between them. 

Connection-mode 

A circuit-oriented mode of transfer in which data are passed 
from one user to another over an estabhshed connection in a 
reliable, sequenced manner. 

Connectionless-mode 

A mode of transfer in which data are passed from one user to 
another in self-contained units with no logical relationship 
required among multiple units. 

Connection release 

The phase in connection-mode that terminates a previously esta- 
blished transport connection between two users. 

Datagram A unit of data transferred between two users of the 
connectionless-mode service. 

Data transfer The phase in connection-mode or connectionless-mode that sup- 
ports the transfer of data between two transport users. 

Expedited data Data that are considered urgent. The specific semantics of 

expedited data are defined by the transport protocol that pro- 
vides the transport service. 
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Expedited transport service data 

The amount of expedited user data the identity of which is 
preserved from one end of a transport connection to the other 
(that is, an expedited message). 

Local management 

The phase in either connection-mode or connectionless-mode in 
which a transport user establishes a transport endpoint and 
binds a transport address to the endpoint. Functions in this 
phase perform local operations, and require no transport layer 
traffic over the network. 

Orderly release 

A procedure for gracefully terminating a transport connection 
with no loss of data. 

Peer user The user with whom a given user is communicating above the 
Transport Interface. 

Server The transport user in connection-mode that offers services to 

other users (clients) and enables these clients to establish a tran- 
sport connection to it. 

Service indication 

The notification of a pending event generated by the provider to 
a user of a particular service. 

Service primitive 

The unit of information passed across a service interface that 
contains either a service request or service indication. 

Service request A request for some action generated by a user to the provider of 
a particular service. 

Synchronous execution 

The mode of execution in which Transport Interface routines 
may block while waiting for specific asynchronous events to 
occur. 

Transport address 

The identifier used to differentiate and locate specific transport 
endpoints in a network. 
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Transport connection 

The communication circuit that is established between two tran- 
sport users in connection-mode. 

Transport endpoint 

The local communication channel between a transport user and 
a transport provider. 

Transport Interface 

The library routines and state transition rules that support the 
services of a transport protocol. 

Transport provider 

The transport protocol that provides the services of the Tran- 
sport Interface. 

Transport service data unit 

The amount of user data whose identity is preserved from one 
end of a transport connection to the other (that is, a message). 

Transport user The user-level application or protocol that accesses the services 
of the Transport Interface. 

Virtual circuit A transport connection established in connection-mode. The fol- 
lowing acronyms are used throughout this guide: 



CUTS 



Connectionless Transport Service 
Connection Oriented Transport Service 
Expedited Transport Service Data Unit 
Transport Service Data Unit 



COTS 



ETSDU 



TSDU 
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Background 



Sockets was first introduced in 1981 as part of the Berkeley 4.2 Software Distri- 
bution. A significant application base has been written using this interface. 
Sockets has now been added to UNIX System V Release 4 as part of the 
BSD/System V unification. 

Different approaches are possible within the sockets framework. This chapter 
discusses these approaches and then illustrates them with a series of sample 
programs. The programs demonstrate the use of both datagram socket and 
stream socket communication. The chapter is divided into the following sec- 
tions: The "Basics" section introduces the sockets routines and the basic model 
of communication. "Supporting Routines" describes some of the library func- 
tions that may be used to build distributed applications. The section on the 
"Client/Server Model" discusses the model used in developing applications and 
includes examples of the two major types of servers. "Advanced Topics" 
discusses issues that may be relevant for more sophisticated users. 
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I 

A basic building blcx:k for communication is the socket. A socket is an endpoint 
of communication to which a name may be bound. Each socket in use has a 
type and one or more associated processes. Sockets exist within communica- 
tions domains. Domains are abstractions that imply both an addressing struc- 
ture (address family) and a set of protocols which implement socket types 
within the domain (protocol family). Communications domains are introduced 
to bundle common properties of processes communicating through sockets. 
One such property is the scheme used to name sockets. In the UNIX domain, 
sockets are named with UNIX pathnames; for example, a socket may be named 
/dev/foo. Sockets normally exchange data only with sockets in the same 
domain (it may be possible to cross between communications domains, but only 
if some translation process is performed). The UNIX system socket interface 
facilities support several separate communications domains: for example, the 
UNIX domain, for on-system conununication; and the Internet domain, which is 
used by processes that communicate using the DARPA standard communication 
protocols. The underlying communication facilities provided by the§e domains 
have a significant influence on the internal system implementation as well as the 
interface to socket facilities available to a user. For example, a socket operating 
in the UNIX domain sees a subset of the error conditions that are possible when 
operating in the Internet domain. 

Socket Types 

Sockets have types that reflect the communication properties visible to a user. 
Processes are presumed to communicate only between sockets of the same type, 
although there is nothing that prevents communication between sockets of dif- 
ferent tj^s should the underl5dng communication protocols support this. 

There are several types of sockets currently available: 

■ A stream socket provides for the bidirectional, reliable, sequenced, and 
unduplicated flow of data without record boundaries. A pair of con- 
nected stream sockets provides an interface nearly identical to that of 
pipes. 

■ A datagram socket supports bidirectional flow of data that is not prom- 
ised to be sequenced, reliable, or unduplicated. That is, a process receiv- 
ing messages on a datagram socket may find messages duplicated and 
possibly in an order different from the order in which they were sent. An 
important characteristic of a datagram socket is that record boundaries in 
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the data are preserved. Datagram sockets closely model the facilities 
found in many contemporary packet switched networks such as the Ether- 
net. 

■ A raw socket provides access to the underlying communication protocols 
that support socket abstractions. These sockets are normally datagram 
oriented, although their exact characteristics are dependent on the inter- 
face provided by the protocol. Raw sockets are not intended for the gen- 
eral user; they have been provided mainly for users interested in develop- 
ing new communication protocols, or gaining access to some of the more 
esoteric facilities of an existing protocol. The use of raw sockets is con- 
sidered under "Advanced Topics'' below. 



Socket Creation 

The socket () system call is used to create a socket: 

s = socket (domain, type, protocol); 

This call requests that the system create a socket in the specified domain and of 
the specified type. If the protocol is left unspecified (a value of 0), the system 
will select an appropriate protocol from those that comprise the domain and 
that may be used to support the requested socket type. A descriptor (a small 
integer) that nnay be used in later system calls that operate on sockets is 
returned. The domain is specified as one of the manifest constants defined in 
the file <sys/ socket . h>. For the UNIX domain the constant is AFJONIX; for the 
Internet domain, it is AF INET. 



mm 



The constants named AFjvhatever show the address format to use in inter- 
preting names. 



The socket types are also defined in <sys/socket . h> and one of 
SOCK_STREAM, SOCKDGRAM, or SOCK_RAW must be specified. To create a 
stream socket in the Internet domain the following call might be used: 

s « socket (AF INET, SOCK STREAM, 0) ; 
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This call would result in a stream socket being created with the TCP protocol 
providing the underlying communication support. To create a datagram socket 
for on-machine use the call might be: 

s - socket (AFJJNIX, SCX:kJ)GRAM, 0) ; 

The default protocol (used when the protocol argument to the socket () call is 
0) should be correct for most situations. However, it is possible to specify a 
protocol other than the default; this will be covered in the "Advanced Topics" 
section below. 

A socket call may fail for several reasons. Aside from the rare occurrence of 
lack of memory (ENOBUFS), a socket request may fail because the request is for 
an unknown protocol (EPROTONOSUPPORT), or because the request is for a type 
of socket for which there is no supporting protocol (EPROTOTYPE). 



Binding Local Names 

A socket is created without a name. Until a name is bound to a socket, 
processes have no way to reference it and consequently no messages may be 
received on it. Communicating processes are bound by an association. In the 
Internet domain, an association is composed of local and foreign addresses, and 
local and foreign ports, while in the UNIX domain, an association is composed 
of local and foreign pathnames. 



NOTE 



The phrase "foreign pathname" means a pathname created by a foreign pro- 
cess, not a pathname on a foreign system. 



In most domains, associations must be unique. In the Internet domain there 
may never be duplicate tuples, such as: 

<protocol, local address, local port, foreign address, foreign port> 

UNIX domain sockets need not always be bound to a name, but when bound 
there may never be duplicate tuples of the type: 

<protocol, local pathname, foreign pathname> 

Currently, the pathnames may not refer to files already existing on the system, 
though this may change in future releases. 
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The bind 0 system call allows a process to specify half of an association, for 
example 

<local address, local port> (or <local pathnanie>) 

while the connect () and accept () primitives are used to complete a socket's 
association. 

The bindO system call is used as follows: 

bind(s, name, namelen); 

The bound name is a variable length byte string that is interpreted by the sup- 
porting protocol(s). Its interpretation may vary between communication 
domains (this is one of the properties that comprises a domain). Whereas Inter- 
net domain names contain an Internet address and port number, UNIX domain 
names contain a pathname and a family. The family is always AFJUNIX. The 
following code would be used to bind the name /tirp/foo to a UNIX domain 
socket: 

3ty<w<acidr,»un_path, "/twp/foo'*) ; 
addr.svm_famlly ^ AFjmx; 

J>ind(9, {9%r\i<X 9Pckaddr *) fiaddr, strlen(a<3dr.sunj>ath> + 
stzeo^ (ac|cir,sun__family)); 



Note that in determining the size of a UNIX domain address, null bytes are not 
counted, which is why strlen () is used. The file name referred to in 
addr . sun_path is created as a socket in the system file space. The caller 
must, therefore, have write {permission in the directory where addr . sun_path 
is to reside, and the file should be deleted by the caller when it is no longer 
needed. 

In binding an Internet address things become more complicated. The call itself 
is similar. 
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struct dodcaddrjii ain; 

blnd(0# (struct soclead:!? *J t»*i>/ #t«©of «4^i> ; 



but the selection of what to place in the address sin requires some discussion. 
We will come back to the problem of formulating Internet addresses in the 
"Supporting Routines" section when the library routines used in name resolu- 
tion are discussed. 

Connection Establishment 

Connection establishment is usually asymmetric, with one process a client and 
the other a server . The server, when willing to offer its advertised services, 
binds a socket to a well-known address associated with the service and then 
passively listens on its socket. It is then possible for an unrelated process to 
rendezvous with the server. The client requests services from the server by ini- 
tiating a connection to the server's socket. On the client side the connect () 
call is used to initiate a connection. In the UNIX domain, this might appear as: 



connect (5, (Atxvtct aodcaddr *)^a^tv^r, 

gtrleai (server. smi_j>ath) + sizeof (server. sun__fainily) > ; 



while in the Internet domain, it might be: 



struct 90c)£add£j>n. ^ezvfu:; 

cCnitect(d, (sttuct sockaddr ^)&server, sizeof server); 
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server would contain either the UNIX pathname, or the Internet address and 
port number of the server to which the client process wishes to speak. If the 
client process's socket is unbound at the time of the connect call, the system will 
automatically select and bind a name to the socket if necessary. See "Signals 
and Process Groups" below. This is the usual way that local addresses are 
bound to a socket. 

An error is returned if the connection was unsuccessful (however, any name 
automatically bound by the system remains). Otherwise, the socket is associated 
with the server and data transfer may begin. Some of the more common errors 
returned when a connection attempt fails are: 

ETIMEDOUT After failing to establish a connection over a period of time, the 
system stopped attempting the connection. This may occur 
when the destination host is down or when problems in the net- 
work result in lost transmissions. 

ECONNREFUSE 

The host refused service. This usually occurs when a server 
process is not present at the requested name. 

ENETDOWN or EHOSTDOWN 

These operational errors are returned based on status informa- 
tion delivered to the client host by the underlying communica- 
tion services. 

ENETUNREACH or EHOSTUNREACH 

These operational errors can occur either because the network or 
host is unknown (no route to the network or host is present), or 
because of status information returned by intermediate gateways 
or switching nodes. The status returned is not always sufficient 
to distinguish between a network that is down and a host that is 
down. 

For a server to receive a client's connection it must perform two steps after 
binding its socket. The first is to listen for incoming connection requests. With 
a socket marked as listening, the second step is to accept () a connection: 
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struct dodcaaarjLn trxm 

newsock - accept ^9 » (struct sockaddr *) &f rom, 4f romlen) / 

V J 

The first parameter to the listen () call is the socket on which the connection 
is to be established. The second parameter to the listen () call specifies the 
maximum number of outstanding connections that may be queued awaiting 
acceptance by the server process. (For the UNIX domain, from would be 
declared as a struct sockaddr un but nothing different would need to be done 
as far as f romlen is concerned. In the examples that follow, only Internet rou- 
tines will be discussed.) A new descriptor is returned on receipt of a connection 
(along with a new socket). If the server wishes to find out who its client is, it 
may supply a buffer for the client sockef s name. The value-result parameter 
f romlen is initialized by the server to indicate how much space is associated 
with from. It is then modified on return to reflect the true size of the name. If 
the client's name is not of interest, the second parameter may be a null pointer. 

accept ( ) normally blocks. That is, accept ( ) will not return until a connec- 
tion is available or the system call is interrupted by a signal to the process. 
Further, there is no way for a process to indicate that it will accept connections 
only from a specific individual or individuals. It is up to the user process to 
consider who the connection is from and close down the connection if it does 
not wish to speak to the process. If the server process wants to accept connec- 
tions on more than one socket, or wants to avoid blocking on the accept call, 
there are alternatives; they will be considered in the ''Advanced Topics" section 
below. 



3-8 



Programmer's Guide: Networking Interfaces 



Basics 



Data Transfer 

With a connection established^ data may begin to flow. There are several calls 
for sending and receiving data. With the peer entity at each end of a connection 
anchored, a user can send or receive a message without specifying the peer. 
Here, the normal read () and write () system calls are usable: 

i4rdlt«»<fl^ h\3tt diaidof buf ) ; 
zBa4(s, buf^. sizeof buf); 

V J 

In addition to read () and write () , the calls send () and recv () may be 
used: 

send(s, buf, sizeof buf, flags); 
recv(s, buf, sizeof buf, flags); 

While sendO and recv() are virtually identical to read() and write () , 
the extra flags argument is important The flags, defined in 
<sys/ socket . h>, may be specified as a non-zero value if one or more of the 
following is required: 

MSG_OOB send/receive out-of-band data 

MSG_PEEK look at data without reading 

MSG_DONTROUTE send data without routing packets 

Out-of-band data is specific to stream sockets. The option to have data sent 
without routing applied to the outgoing packets is currently used only by the 
routing table management process and is unlikely to be of interest to most 
users. However, the ability to preview data is of interest. When MSG_PEEK is 
specified with a recv () call, any data present is returned to the user but 
treated as still unread. That is, the next read {) or recv () call applied to the 
socket will return the data previously previewed. 
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Closing Sockets 

Once a socket is no longer of interest, it may be discarded by applying a 
close 0 to the descriptor, 

close (s) ; 

If data is associated with a socket that promises reliable delivery (for example, a 
stream socket) when a close takes place, the system will continue to attempt to 
transfer the data. However, if the data is still undelivered after a fairly long 
period of time, it will be discarded. If a user has no use for pending data, a 
shutdown ( ) may be performed on the socket before closing it. This call is of 
the form: 

shutdown ( s , how) ; 

where how is 0 if the user is no longer interested in reading data, 1 if no more 
data will be sent, and 2 if no data is to be sent or received. 

The following two code samples illustrate how to initiate and accept an Internet 
domain stream connection. 



Figure 3-1 : Initiating an Internet Domain Stream Connection 



#±nclTide <sys /types *h> 

llndude <aetinet/ia,h> 
linQlude •Oiet<ib.h> 

♦define naTA "M^lf a league, J^aiJE » ^jeague 



* Ttiift pzogram creates a socket and initiates a connection with the socket 

* given in the conmand line. One message is sent over the connection and 

* then the socket is closed, ending the ccffinection. . The form of the conmand 

* line is^ streantwrite hostnanie portnureber 



inain(argcr aigv) 

int axgc; 
char *argvtl; 



(continued on next page ) 
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Figure 3-1: Initiating an Internet Domain Stream Connection (continued) 



itit sock; 

9tcuct sockaddr^in server; 

Struct hostent *hp^ *gethostl3(ynaifte(); 

dhar buf [10243; 

/* Ct»^te socket, */ 

sock « socket (AF_INET, S0C2C_STREftM, 0) ; 

±t (sock < 0) { ^ 

perror(^Op(gnlDg stxeaM docket^); 
exit (1); 

liiiiillllllllii 

/* Connect socket Using name specified by conmand line, */ 
server, sln_f ami ly - AF^INET; 
hp ^ gethostbyna»e<a£gv{XJ); 
if 0^ 0) { 

fprintf (stcterr, **%s: iinknown hostXtt**^ argv[l]); 

exit (2) ; 

jnewK2py < (char *)&server.sttt_adar, (char *)hp->hjSK3dr^ 

hp-->h_length) ; " 
server . sinjwrt - htons (atol (argv [2] ) ) ; 

if (connect (sock, 

(struct sockaddr *)Aserver^ slzeof server ) < 0> { 
perrorC»connecting stream socket ♦*>; 
exit (1); 

if (write (sock, DATA, sizeof DATA ) < 0) 

perror(«writing on stream socket") ; 
close (sock); 
exit (0) ; 
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Figure 3-2: Accepting an Internet Domain Stream Connection 

. __ ^ 

#lnciii3<}0 <3ys /types, h> 
#inclT3de <sys/socket»h> 
llnclude ■<iietinet/lii.h> 

fiiidXttefe <dtdlo.h> 



* V^in pxogxm cwwtcw ft socket «nd then begins an tnflntte locp. each time 

* th£6u^ the Kxip it access a Cctfmectlon and ptlntSi ^ut medsai^ed from it. 

* When the connection bzeaks, or a tezndnatlon messai^e corner t^izou^, the 

* p^tm ^iccepts ft neir connection. 



minO 

int sock, lenigrt^h; 

struct dockaddrlA server; 

int msgsock; 

char bttf {10243 i 

int t^l: 



/* Cteate socket. */ 

sock » socket (MLINET, SOCaCJSTREAM, 0) ; 

Ui (soc* < 0) { 

peE£0t(*»4a!petiin^ stream socket^); 
exit CD; 

/* tidlne dOdket Mdim^ midcatds. */ 
seraeT^sinjeamily - AP^lHET; 

server «sinjport d; 

if g>in(S(sock^ {struct aockaddr *)4server^ sizeof sen;er > <: 0) { 
perrorC^'bindin^ stzeatn socket^); 
exit(l); 

/* Jfind out assigned port number and print it out. */ 
J«t)gtli * sizeof server; 

if (getsockna»)e<sock, (struct sockaddr *)*server^ 
^length) < 0) { 

perror(»»getting socket name«>; 
exit(l>; 

printf (••Socket port #%dVi**,» ntohs (server. sittj»rt>); 



(continued on next page) 
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Figure 3-2: Accepting an Internet Domain Stream Connection (continued ) 



/* Statt aoc^ting connections, */ 
list^^sock, 5); 

m^aock - aecdpt(dOdc, <dtzu<% dOckaddr (int 
if (msgsock -X) 

perror ( "aco^ * ) ; 

else do { 

raemsetCbuf, 0* slzeof buf y; 

if ((rval » zead (msgsock^ buf, 1024)) < 0) 

perror ("reading stream message^); 
if (rval — 0) 

printf (^Ending 6onn6cti6n\n" ) ; 

else 

printf (**—>%s\n", buf); 
) while (rval !- 0) ; 
close<msgsoclc>; 
) i^ile (TPSM); 

* Since this program has an infinite loop, the socket **sock** is 
tsever ea^lidtly eloded. Hoi^v^, all sockets ifill be closed 

* a\2tQmatlcally irtien a process is killed or terminates normally. 

exit(0>; 



Connectionless Sockets 

Up to this point we have been concerned primarily with connection-oriented 
sockets. However, connectionless interactions typical of the datagram facilities 
found in contemporary packet switched networks are also supported. A 
datagram socket provides a symmetric interface to data exchange. While 
processes are still likely to be client and server process, there is no requirement 
for connection establishment. Instead, each message includes the destination 
address. 
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Datagram sockets are created as described above under "Socket Creation/' If a 
particular local address is needed, the bind () operation must precede the first 
data transmission. Otherwise, the system will set the local address and/or port 
when data is first sent. To send data, the sendto () call is used: 

sendto(s, buf, buflen, flags^ (struct sockaddr *) 
&to, tolen) ; 

The s, buf , buf len, and flags parameters are used the same as with 
connection-oriented sockets. The to and tolen values are used to indicate the 
address of the intended recipient of the message. When using an unreliable 
datagram interface, it is unlikely that any errors will be reported to the sender. 
When information is present locally that allows the system to recognize a mes- 
sage that can not be delivered (for instance when a network is unreachable), the 
call will return -1 and the global value errno will contain the error number. 

To receive messages on an unconnected datagram socket, the recvf rem () call 
is used: 

recvf rem (s, buf, buf len, flags, (struct sockaddr *) 
fifrom, &f romlen) ; 

The f romlen parameter initially contains the size of the from buffer; it is 
modified on return to show the size of the address from which the datagram 
was received. 

In addition to the two calls mentioned above, datagram sockets may also use 
the connect () call to associate a socket with a specific destination address. 
Here, any data sent on the socket without expliciUy specifying the destination 
address will automatically be addressed to the connected peer, and only data 
received from that peer will be delivered to the user. Only one connected 
address is permitted for each socket at one time. A second connect will change 
the destination address, and a connect to a null address (domain AF_UNSPEC) 
will disconnect. Connect requests on datagram sockets return immediately; the 
system simply records the peer's address. By contrast, a connection request on 
a stream socket initiates establishment of an end-to-end connection. 

accept 0 and listen () are not used with datagram sockets. 

While a datagram socket is connected, errors from recent send () calls may be 
returned asjmchronously. These errors may be reported on subsequent opera- 
tions on the socket, or a special socket option used with getsockopt, 
SO_ERROR, may be used to interrogate ti\e error status. 
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Figure 3-3: Reading internet Domain Datagrams 



* ^Ibd include file <netlnet/in.h> defines aodcaddrJLn as follo^dt 

* struct 30C)caddr^in f 

* »hOJCt aln^faanlly; 
^ u^ahort Siisij^tt;! 

* Struct injBuqtdr sinjadklUr; 
« cihar ain asecotS]; 

« this px:ogri»m cxtitttes a datagxiam soclcet^ binds a name to it« then xeads 
-x^ fzom t^ socket' 

int sockr length; 
artinict sockaddi^^in name; 
Char huf [1024];^ 



/♦ Create socket from vdiich to read. */ 
sock - socket (AF_INET, SOCKJXSRfiM, 0); 
if (sock < 0) { 

perzor("openin9 datagram aocket"); 

exlt(l); 

iiiiiiiiiliiiiiiiiiiiM^^^^ 

/* Create name with wildcards. */ 



na 


me. 


sin 


/amily 


- AP^llilBT^ 






name. 


sin^ 


addr 


.S addr « ZNADDR ANY; 






name. 


sln^jKot 




0; 






if 


(bind (sock, 




(st£UCt SCCkaddUr ^)«nakne, 






siseof 


name 


) 


<0) ( 












perror (^binding datagram socket 





eatita)^ 

/* Find assigned port value and print it out. * 
length ^ sizeof (name) ; 

if (getsockname^sock^ (struct sockaddr «)[6name/ 
&lea:)gth) < OH ( 

P^aKMr<«getting sodcet name"); 
e3(ita); 



(continued on next page ) 
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Figure 3-3: Reading Internet Domain Datagrams (continued ) 

liiiiiliiiiiiii^iiiiiii^^^ 

printf ("Socket port #%dNn", ntohs (nan».sinj>ort> ) ; 
/* Raad fron the 90cKet, */ 
if (jfead(sock, buf, X024) < 0) 



perzorC^zedeiving datagram packet**); 




printf >%3\n«^ \>Mf)i 




Close (sock); 






exit (0) ; 

lllllllllllllllilll^ 













Figure 3-4: Sending an Internet Domain Datagram 



flnclude <5ys /types. h> 
♦include <sYs/sooket,h> 
linclude <netinet/in.h> 
linclude <iietdb.li> 
#inelude <dtdio.h> 

Idefine DATA "T^he aea ia cal*n^ the tide is full . , .* 

iiiiiiiiiiiiiiiiiiiiii;! 

* Here I sehd a datagram to a receiver **ose nawe I get from the command 

* line arguments. The form of the comnand line is: 

* dgramsend hostname portnumber 



main(argcy argv) 

int argd; 



int sock; 

strtict sockaddr_ln name; 

struct hostent *hp^ *gethostbyname<) ; 

/* Create socket on which to s^d, */ 
sock m socket <AFJtNE!r, flOCKjXSAM, 0); 
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Figure 3-4: Sending an Internet Domain Datagram (continued ) 

it (sock < 0) { 

iiiiiiiiiiiiiiiiiiiiiiiiiiiiiii 

* Construct nama^ with no wildcards* of the socket to 8en<J to. 

* oethofltt^ame returns a structui» Including the network address 

* of the ^>eclfied host. The port number Is taken from the coiraiand 

* line. 

hp m gethostbynaina(argv{l]); 
if 0^ — 0) i 

fprintf (stderr, *»%s: unknown host \n^y^ argvtl)); 

exit (2); 

iiiiiiiiiiiiiiiiiiiiiiiiiiiii^ 

memcp^C (<diar *) finaine.siii_addr, (char *)hp->h_addr, 

hp->h_length) ; 
name.sin^family » AF^tNEt; 
naine.sin_port htons(atoi(az9v[2] )) ; 
/* Send message, */ 

if (sendto(sock, DATA, sizeof t>ATA , 0, 

(Struct sockaddr *>Anaine* sizeof name) < 0) 
perror (^sending datagram message**); 
close (sock); 
exit (0)7 

V J 



Input/Output Multiplexing 

The ability to multiplex I/O requests among multiple sockets or files is a facility 
that is often used in developing applications. The select () call is used for 
this type of input/output multiplexing: 
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lincXttde <[^d/tl»ft&.h> 
iincluda <dyd/t^>ed.h> 

£djafet v^tSr^sy^t inriteini»3K/ exoctptmsk; 
dt£tict tltnetral tlineout,' 

fleXdctCnfas, «x^da<!knadk^ (vriteiMidfc, t^exod^^tnuutk, ^tiM^ut); 

V ■ J 

select 0 takes pointers to three sets as arguments. One pointer is to the set 
of file descriptors on which the caller wishes to be able to read data; one is to 
those descriptors to which data is to be written; and one is to pending excep- 
tional conditions. Out-of-band data is the only exceptional condition currently 
implemented. If the user is not interested in certain conditions (i.e., read, write, 
or exceptions), the corresponding argument to the select () should be a prop- 
erly cast null pointer. 

Each set is a structure containing an array of long integer bit masks. The size of 
the array is set by FD_SETSIZE. The array is long enough to hold one bit for 
each of FD_SETSIZE file descriptors. 

The macros FD_SET (/d^ fimosfc), and FD_CLR(/d, &mask) have been provided 
for adding and removing file descriptor f d in the set mask. The set should be 
zeroed before use, and the macro FD_ZERO (fimosfc) has been provided to clear 
the set mask. 

The nf ds argument specifies the range of file descriptors (i.e., one plus the 
value of the largest descriptor) to be examined in a set. 

A timeout value may be specified if the selection is not to last more than a 
predetermined period of time. If the fields in timeout are set to 0, the selec- 
tion takes the form of a poll, returning immediately. If the last parameter is a 
NULL p)ointer, the selection will block indefinitely. 
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To be more specific, if the last parameter is a NULL pointer, a return takes 
place only when a descriptor is selectable, or when a signal is received by 
the caller, interrupting the system call. 



select 0 normally returns the number of file descriptors selected. If the 
select 0 call returns because the timeout has expired, the value 0 is returned. 
If the select () terminates because of an error or interrupt, a -1 is returned 
with the error number in errno, and with the file descriptor masks unchanged. 

Assuming a successful return, the three sets will indicate which file descriptors 
are ready to be read from, written to, or have exceptional conditions pending. 

The status of a file descriptor in a select mask may be tested with the 
FD_ISSET ifd, SLtnask) macro, which returns a non-zero value if f d is a 
member of the set mask, and 0 if it is not. 

To determine if there are connections waiting on a socket to be used with an 
accept 0 call, select () can be used, followed by a FD__ISSET (fd, &mask) 
macro to check for read readiness on the appropriate socket. If FD_ISSET 
returns a non-zero value, indicating permission to read, then a connection is 
pending on the socket. 

As an example, to read data from two sockets, si and s 2, as it is available from 
each and with a five-second timeout, the following code might be used: 
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Figure 3-5: Using select () to Chedc for Pending Connections 



#inciiide <SY3 /types, h> 
#itt<5lTide <»y»/sodcet,h> 
llnclude <syp/t;linB.h> 

fineXiitdd <tietdb.h> 
♦include <:8t<Jlo.h> 



* ptx^rdltt Ud^d Ml66t tA dtledc that 

* Ys^£qx^ calling ^qq^. 



ia ttjfit^ to t/XiiKdCt 



Int.fiock, ieongth; 

atruct aockatiklr^lD aexwer; 

•LML ma^aock; ^ 

<^ar buf [10241; 

int xval; 

f d^set ready; 

atnaet tlmeval to; 

/* Create socket. */ 

sock - socket (AF__1NET^ SOCKJ5TREM4, 0>; 
if <sock < 0) { 

perrorC^^openlng stream socket**}; 

exitil^; 

y* tiame socket using wil<5cards. */ 
server.ainjfamlly - AF^INBT; 
server^ sln_addr*s__addr « INADDR_ANY; 
server, sinjport - 0; 

if (bind (sock, (struct sockaddr *)4server, 
sizeof server) < 0) { 

perror(*'biaidi«g at»6a» socket**}; 
exit(l); 

/* Find out assigned port number and print it out, V 
lencfth » slzi^of server; 

if (getaoaknaine(50ck^ (struct sockaddr «>&server, 
fili^gth) < 0) { 

pezxort'getting socket name"}; 
^t(i); 



(continued on next page) 
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Figure 3-5: Using select () to Checi( for Pending Connections (continued) 



prlntf ("Socket pott #%d\i!i'*r hbdhd{sezif^.iitijp&£t)} ; 

/* Start aocepting conndctiotw. */ 
listen (sock, 5); 



PDJHSftO (&xieady> ; 
FD_SET<sock, tready); 
to.tv^sec * 5; 

If (select (sock + 1, Steady, <fd_set *)0,. 
(fd^set *)(ir fcto) < 0) ( 
perror (*♦ select •* ) ; 
contintaa; 

it (n)_XSSEir(sock^ steady)) { 

insgsock « accept (sock, (struct sockaddr *)0, 

(t?it *)0); 
If (naqaOdn -1) 

perrorr{^acoept'') ; 

4dlse do { 

meinset<buf, 0, sizeof buf); 
if ((rval - readdnsgsock, J>uf, 1024)) < 0) 
petror(**teading stteaw message"); 
else if (rval — 0) 



else 

) irtjile (rval > 0}i 
<$Xd8e(insgsock) ; 



printf ("Ending ccnnection\n**) ; 
printf ( "— >%s\n" , buf) ; 



} else 

) %diile (TE^};^ 
exittWf 



printf ("3Do something else\tt">; 



In previous versions of select () , its arguments were pointers to integers 
instead of pointers to fd_sets. This type of call will still work as long as the 
number of file descriptors being examined is less than the number of bits in an 
integer; however, the methods illustrated above should be used in all current 
programs. 
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select 0 provides a synchronous multiplexing scheme. The SIGIO and 
SIGURG signals described in the "Advanced Topics" section below may be used 
to provide asynchronous notification of output completion, input availability, 
and exceptional conditions. 
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The discussion in the "Basics" section above mentions the possible need to 
locate and construct network addresses when using the communication facilities 
in a distributed environment. To aid in this task several routines have been 
added to the standard C run-time library. In this section we will consider the 
new routines provided to manipulate network addresses. 

Locating a service on a remote host requires many levels of mapping before 
client and server may communicate. A service is assigned a name that is 
intended for human consumption; e.g., the login server on host monet. This 
name, and the name of the peer host, must then be translated into network 
addresses that are not necessarily suitable for human consumption. Finally, the 
address must then be used in locating a physical location and route to the ser- 
vice. The specifics of these three mappings are likely to vary between network 
architectures. For instance, it is desirable for a network not to require hosts to 
be named in such a way that their physical location is known by the client host. 
Instead, underl5ning services in the network may discover the location of the 
host at the time a client host wishes to communicate. This ability to have hosts 
named independent of their location may induce overhead in connection estab- 
lishment, as a discovery process must take place, but allows a host to be physi- 
cally mobile without requiring it to notify its clientele of its current location. 

Standard routines are provided for mapping host names to network addresses, 
network names to network numbers, protocol names to protocol numbers, and 
service names to port numbers and the appropriate protocol to use in communi- 
cating with the server process. The file <netdb . h> must be included when 
using any of these routines. 
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Host Names 

An Internet host name to address mapping is represented by the hostent 
structure: 



struct iMOt&at { 

<!har *h^naroa; /» official name of ho9t ♦/ 

Char ♦♦^aliases; /* alias list */ 

itit hjaSdx±^; /♦ host adders type (e.g., AF_INBT> */ 

int h^length; /♦ length pf address */ 

Char **h addr list; /* list of addresses, null t^oninated V 

♦define hjiddy hjaddr^list [0] /♦ first address, network Ijyte order */ 



The routine gethostbyname(3N) takes an Internet host name and returns a 
hostent structure, while the routine gethostbyaddr(3N) maps Internet host 
addresses into a hostent structure. The routine inet__ntoa(3N) maps an 
Internet host address into an ASCII string for printing by log and error mes- 
sages. 

The official name of the host and its public aliases are returned by these rou- 
tines, along with the address type (domain) and a null terminated list of vari- 
able length addresses. This list of addresses is required because it is possible for 
a host to have many addresses, all having the same name. The h_addr 
definition is provided for backward compatibility, and is defined to be the first 
address in the list of addresses in the hostent structure. 



Network Names 

As for host names, routines for mapping network names to numbers, and back, 
are provided. These routines return a netent structure: 
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^ Adauiiiptl6A t)d£!6 id that a ttdtwozk Wttiiber 
* fits in 32 bits probaWy a pooi: one* 

lllllllllllllllllllll^ 
struct net^t { 

Char *nj\me; /* official name of net */ 

ehajt **ti_allases; /* alias list */ 

int n_addrtype; /* net ackJress type */ 

int n net; /* network nuttber, host byte order */ 



The routines ge t net byname (3N), getnetbyaddr (3N) , and getnetent (3N) 
are the network counterparts to the host routines described above. 



Protocol Names 

For protocols, the protoent structure defines the protocol-name mapping used 
with the routines getprotobyname(3N), getprotobynunvber(3N), and 
getprot cent (3N): 



struct protoent { 
Char *pj»a»ie; 
char **pjatliases,^ 
int Fyproto; 



/* official protocol naine */ 

/♦ alias list V 

/* protocol number */ 
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Service Names 

Information regarding services is a bit more complicated. A service is expected 
to reside at a specific port and use a particular communication protocol. This 
view is consistent with the Internet domain, but inconsistent with other network 
architectures. Further, a service may reside on multiple ports. If this occurs, the 
higher level library routines will have to be bypassed or extended. 

A service mapping is described by the servent structure: 



struct servent { 

chai: *8jwu«e; /♦ official service name */ 

char ♦♦s^aliades; /* alias list */ 

int sjport; /* port number, network byte order V 

char *s^j>roto; /♦ protocol to use */ 



The routine getservbyname(3N) maps service names to a servent structure 
by specifying a service name and, optionally, a qualifying protocol. Thus the 
call 

sp = get servbyname ("telnet", (char *) 0) ; 

returns the service specification for a telnet server using any protocol, while the 
call 

sp = get servbyname ("telnet", "tcp"); 

returns only that telnet server that uses the TCP protocol. The routines 
getservbyport(3N) and getservent(3N) are also provided. The get- 
servbyport () routine has an interface similar to that provided by get- 
servbyname () ; an optional protocol name may be specified to qualify lookups. 
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Miscellaneous 

With the support routines described above, an Internet application program 
should rarely have to deal directly with addresses. This allows services to be 
developed as much as possible in a network independent fashion. It is clear, 
however, that purging all network dependencies is very difficult. So long as the 
user is required to supply network addresses when naming services and sockets 
there will always be some network dependency in a program. For example, the 
normal code included in client programs, such as the remote login program, is 
of the form shown in Figure 3-6. (This example will be considered in more 
detail in the "Client/Server Model" section below.) 

Aside from the address-related database routines, there are several other rou- 
tines available in the run-time library that are of interest to users. These are 
intended mostly to simplify manipulation of names and addresses. Table 3-1 
summarizes the routines for manipulating variable length byte strings and han- 
dling byte swapping of network addresses and values. 



Table 3-1 : Run-Time Library Routines 



Call 


Synopsis 


memcmp (si, s2, n) 
memcpy{sl, s2, n) 
memset (base, value, n) 
htonl (val) 
htons (val) 
ntohl (val) 
ntohs (val) 


Compare byte-strings; 0 if same, not 0 otherwise 

Copy n bytes from s2 to si 

Set n bytes to value starting at base 

32-bit quantity from host into network byte order 

16-bit quantity from host into network byte order 

32-bit quantity from network into host byte order 

16-bit quantity from network into host byte order 



The byte swapping routines are provided because the operating system expects 
addresses to be supplied in network order. On some architectures, such as the 
VAX, host byte ordering is different from network byte ordering. Consequently, 
programs are sometimes required to byte swap quantities. The library routines 
that return network addresses provide them in network order so that they nmy 
simply be copied into the structures provided to the system. Users should 
therefore encounter byte swapping problems only when interpreting network 
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addresses. For example, the following code will print out an Internet port: 

printf("port number %d\n", ntohs (sp->s_port) ) ; 

On certain machines, where these routines are not needed, they are defined as 
null macros. 

Figure 3-6: Remote Login Ciient Code 



llndude <sy5 /types. h> 
♦include <sy3/3oc)cet,h> 
#incli3de <netlnet/ln.h> 
finclude <j5tclio.h> 
♦indiudei <w!tdb .h> 

jnain(ar3C, argv) 

int. iLPgc; 
char *argvtj; 



struct sockaddr^in server; 
struct servent *3p; 
struct hostent *hp; 

sp w getser^ynameC^login", "tcp**); 
if (sp NULL) { 

fprintf (stderr, *rlogin: tcp/Iogin: unknown service\tt**>; 

exit(l); 
llllllllllllllliill;^ 
hp - gethostbyname (argv IX])/ 
if (hp NULL) { 

f printf (stderr* "rlogin; %s: unknown hostNn'*^ argv^l]); 

exit (2); 

tftemset ( (char *) ^server, 0, si^eof server) ; 

inenK^y((cfaar ♦) t server. sin_addr, l^->hjaddr, l^:^_length) ; 

server, sinjfamily - hp->h_addrtype; 

server. sin^port * sp->s^rt; 

S socket (AFJINET, SCX3U5TREAM, 0); 
if (S < 0) ( 

perrorC^r login: socket**); 

exit (3); 

iiiiiiiiiiiiiiiiliiiiilil 

/* Connect does the bind for us */ 



(continued on next page) 
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Figure 3-6: Remote Login Client Code (continued) 



it (oomiect(S/ (struct »ocic«*ir *)iaervi©r, alzeof server) < 0) f 
perror < '*rlogin : csannect** ) ; 
exit (5) ; 



) 

exit(O); 
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The most commonly used paradigm in building distributed applications is the 
client/server model. In this scheme client applications request services from a 
server process. This implies an asymmetry in establishing communication 
between the client and server that has been examined in the "Basics" section 
above. In this section we will look more dosely at the interactions between 
client and server, and consider some of the problems in developing client and 
server applications. 

The client and server require a well known set of conventions before service 
may be rendered (and accepted). This set of conventions comprises a protocol 
that must be implemented at both ends of a connection. Depending on the 
situation, the protocol may be symmetric or asymmetric. In a symmetric proto- 
col, either side may play the master or slave roles. In an asymmetric protocol, 
one side is immutably recognized as the master, with the otf\er as the slave. An 
example of a symmetric protocol is the TELNET protocol used in the Internet for 
remote terminal emulation. An example of an asymmetric protocol is the Inter- 
net file transfer protocol, FTP. No matter whether the specific protocol used in 
obtaining a service is symmetric or asjonmetric, when accessing a service there 
is a client process and a server process. We will first consider the properties of 
server processes, then client processes. 

A server process normally listens at a well known address for service requests. 
That is, the server process remains dormant until a connection is requested by a 
client's connection to the server's address. At such a time the server process 
"wakes up" and services the client, performing whatever appropriate actions 
the client requests of it. 

Alternative schemes that use a service server may be used to eliminate a flock of 
server processes clogging the system while remaining dormant most of the time. 
For Internet servers, tfiis scheme has been implemented via inetd, the so called 
"internet super-server." inetd listens at a variety of ports, determined at 
start-up by reading a configuration file. When a connection is requested to a 
port on which inetd is listening, inetd executes the appropriate server pro- 
gram to handle the client. With this method, clients are unaware that an 
intermediary such as inetd has played any part in the connection, inetd will 
be described in more detail in the "Advanced Topics" section below. 
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Servers 



In the UNIX system, most servers are accessed at well known Internet addresses 
or UNIX domain names. The form of their main loop is illustrated by the fol- 
lowing code form the remote-login server: 



Figure 3-7: Remote Login Server 

mi^mtammK^m ■■■■ii 

char *arigv[]; 
Int f ; 

struct sockaddi^in from; 
Struct socJcaddrjLn sin; 
struct servent *apt 



sp - getservbyname<'*logln% **tcp'*); 
if (sp NDLL) { 

fprintf <stcterr, 

''rloglnd: tc?>/login: un)cnown serviceXn'*) ; 

exitd); 

I* msassociate B^rver from controlling temvlnaX. */ 



sin.sinjport » sp->sjport; /* Restricted port */ 
sitt.slttj9ddr,s_addr - JKADDRAN^; 

f - socket (AP_IIIET^ SOOLSTRERH, 0); 

if (bind(f, (struct sockaOdr *) Ssin, sl^eof sln)^ < 0^ { 

Xist^(f, 5); 
for (;;) { 

int len * si^seof from; 

g accept (£, (struct soqkad^r fifrqin, filen); 
if (g < 0> { 

) 

(continued on next page ) 
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Figure 3-7: Remote Login Server (continued) 



14r (ermo !- eiMm> 



continue; 

it <£ork() ^ 0) { 
close (f); 
dolt^g, «£rom); 

lllllllllllllllllilll 
close (g); 



} 

exit(O); 



The first step taken by the server is look up its service definition: 

if (sp — vmL) ( 

fprintKstdeix, 

''rlogind: tcp/login; unknown service\n"); 

exit(l); 




The result of the getservbyname () call is used in later portions of the code to 
define the Internet port at which it listens for service requests (indicated by a 
connection). Some standard port numbers are given in the file 
/usr/include/netinet/in.h for backward compatibility purposes. 

Step two is to disassociate the server from the controlling terminal of its 
invoker: 
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( ^ 

tot <i m getdtabld»lw>()-l; 1 >- 0; —1) 

<S^p4(0, 1); 
auc|>2(0^ 2); 

1 « op^r/dtev/tty", OJRDWR); 

if a Q) { 

closed) ; 

iiiiiiiiliilliiiil 

v__ J 

This step is important as the server will likely not want to receive signals 
delivered to the process group of the controlling terminal. Note, however, that 
once a server has disassociated itself it can no longer send reports of errors to a 
terminal, and must log errors via syslog () . 

Once a server has established a pristine environment, it creates a socket and 
begins accepting service requests. The bind () call is required to insure the 
server listens at its expected location. Note that the remote login server listens 
at a restricted port number, and must therefore be run with a user-id of root. 
This concept of a "restricted port number" is covered in the "Advanced Topics' 
section below. 

The main body of the loop is simple: 
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iiiiliiiiiiiiiiiiiiiiiiiiiii 

lAt ^, len « sisedf from; 

9 ^ accept <f, <atruct sodcaddr «][«froiii/ )tXdn>; 
if < 0) { 

\t <«rmo ranR) 

dyslog(LOGjgRR, '♦rlciglnd: accept: tm"); 

continue; 

iiiiiiiiiiiiiiiiiiiiiiiiiiil^^^^^^ 

if (fotkO ^ Q> ^ /♦ Child V 
close (f>; 
dolt(g/ ifrcw); 

iiiiiiiiiiiliiiiiiiiiiiii^ 

close (g); /* Parent ♦/ 

) 

An accept () call blocks the server until a client requests service. This call 
could return a failure status if the call is interrupted by a signal such as 
SIGCHLD (to be discussed in the "Advanced Topics" section below). Therefore, 
the return value from accept ( ) is checked to insure a connection has been 
established, and an error report is logged via syslog () if an error has 
occurred. 

With a connection in hand, the server then forks a child process and invokes the 
main body of the remote login protocol processing. Note how the socket used 
by the parent for queuing connection requests is closed in the child, while the 
socket created as a result of the accept () is closed in the parent. The address 
of the client is also handed the doit () routine because it requires it in authen- 
ticating clients. 



Clients 

The client side of the remote login service was shown earlier in Figure 3-6. One 
can see the separate, asymmetric roles of the client and server clearly in the 
code. The server is a passive entity, listening for client connections, while the 
client process is an active entity, initiating a connection when invoked. 
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Let us consider more closely the steps taken by the client remote login process. 
As in the server process, the first step is to locate the service definition for a 
remote login: 



ap » get5iervi)ynama(" login", "tqp"); 
it (5P — NTO-y { 

fj>rltttf (stdsl*, 

"rlogln: tqp/login; rniknoun aervloe\n*') ; 



) 



Next the destination host is looked up with a gethostbyname () call: 



hp - getho3tbynarae(argv[l] ) ; 
if (hp — MULL> { 

fprintf (stderr, "rlogin: %s: lanknown hostXn**, argvjl]); 



exit(2>; 



) 



With this done, all that is required is to establish a connection to the server at 
the requested host and start up the remote login protocol. The address buffer is 
cleared, then filled in with the Internet address of the foreign host and the port 
number at which the login process resides on the foreign host: 



mwset((char *}&server, 0, sizeo£ sezv^ry; 

merncpy < <Ghar *) wezv^r,sin_addr^ hp->ii_addr, hp*>h_length) ; 

server. slnjfaraily * hp->h^addrtype; 

ser5/er,3injx>rt * sp-'>sj>ort; 



A socket is created, and a connection initiated. Note that connect () implicitly 
performs a bind () call, since s is unbound. 
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s m docket (btK>h addrtype, SOCK StCRBAM, 0); 
If <a < OM ~ ^ 

perrorCrlogln; sodcet"); 

exit (3); 

iiiiiiliiiiiliiliiiliiii 

if <comieCt(s, (stxuct aockaddr ^^fiseiver, 
sizeof server) < 0) ( 

pertor(*'rXogin: cotmect"); 
ejcit<4); 

\ 

The details of the remote login protocol will not be considered here. 



Connectionless Servers 

While connection-based services are the norm, some services are based on the 
use of datagram sockets. One, in particular, is the rwho service, which provides 
users with status information for hosts connected to a local area network. This 
service, while predicated on the ability to broadcast information to all hosts con- 
nected to a particular network, is of interest as an example usage of datagram 
sockets. 

A user on any machine running the rwho server may find out the current status 
of a machine with the r uptime program. The output generated is illustrated in 
Figure 3-8. 
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Figure 3-8: Output of ruptime Program 
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Status information for each host is periodically broadcast by rwho server 
processes on each machine. The same server process also receives the status 
information and uses it to update a database. This database is then interpreted 
to generate the status information for each host. Servers of>erate autonomously, 
coupled only by the local network and its broadcast capabilities. 

Note that the use of broadcast for such a task is fairly inefficient, as all hosts 
must process each message, whether or not using an rwho server. Unless such 
a service is sufficiently universal and is frequently used, the expense of periodic 
broadcasts outweighs the simplicity. 

The rwho server, in a simplified form, is pictured below. It performs two 
separate tasks. The first is to act as a receiver of status information broadcast by 
other hosts on the network. This job is carried out in the main loop of the pro- 
gram. Packets received at the rwho port are interrogated to insure they've been 
sent by another rwho server process, then are time stamped with their arrival 
time and used to update a file indicating the status of the host. When a host 
has not been heard from for an extended period of time, the database interpreta- 
tion routines assume the host is down and report this information on the status 
reports. This algorithm is prone to error, as a server may be down while a host 
is up. 
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Figure 3-9: ridio Server 

_ ^ 

|||||||||||||||||;^^ 

net K $|Bti)6tb^M(nd<:Alfi^t^)/ 
3in»Binj)0trt ^ atp->dj»rt; 

» *• «OCSlc©tW_JNET^ S0CK_DC3RAM, 0); 

If (aet50Ckopt<a^ S0XJ30CKET, SO_BROADCAST, ion, 
iiieof Oft) < 0) { ^ 

sy3log(lOG_EKRr "«et»ockopt 50_BR0RDCfl3T; 

l>in<3(S/ (atruct sockadkJr *> fisln, slzeof aln); 

signal (SIGALRH, onalxm) ; 

fot (;;) { 

struct i^ocj wcj; 

int ec, ^Atodl, tai * sizeof from; 

CO « 3?ecvf«)iHjs^ (chay »t3seof (stiMct whod)^ 

0, (struct aockaddr *)&froin, ileii); 
If (<sc <- 0) { 

if (cc < 0 <« emjo I- EINTR) 

ayaldg (LOGJBRR, "zwhod: recv: %ro*»>; 

continue; 

if (frQra»ain^j>ort ap->sjport) { 

syslqg (LOGJ»R, "rirticd: %d; bad from port**, 
htohs (f roi!»»sin^jx>rt) ) ; 

continue; 

if <!veri^<wcJ*wdJiostnaine>) { 

e^j»Xdg<LOGBlU^^ *^rwhod: bad boat nam^ from W^, 
ntohl (f rem* sin_addr, ajaddb:) ) ; 

continue; 

(void) sprintf (path, "%s/whod»%s", RSWODIR, 
vKS.vid hostnaaie); 

V 

(continued on next page ) 
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Figure 3-9: rwho Server (continued) 



imod * open(p«t»^ OJWB0liILy|Oj3«»TI0jrR«MC^ 0666); 

(void) write (nJiod, (char *)4;wd^ cc); 
(Void) elGad{whod); 



The second task performed by the server is to supply information regarding the 
status of its host. This involves periodically acquiring system status informa- 
tion, packaging it up in a message and broadcasting it on the local network for 
other rwho servers to hear. The supply function is triggered by a timer and 
runs off a signal. Locating the system status information is somewhat involved, 
but uninteresting. Deciding where to transmit the resultant packet is somewhat 
problematic, however. 

Status information must be broadcast on the local network. For networks that 
do not support the notion of broadcast another scheme must be used to simu- 
late or replace broadcasting. One possibility is to list the known neighbors 
(based on the status messages received from other rwho servers). This, unfor- 
tunately, requires some bootstrapping information, for a server will have no 
idea what machines are its neighbors until it receives status messages from 
them. Therefore, if all machines on a net are freshly booted, no machine will 
have any known neighbors and thus never receive, or send, any status informa- 
tion. This is the identical problem faced by the routing table management pro- 
cess in propagating routing status information. The standard solution, unsatis- 
factory as it may be, is to inform one or more servers of known neighbors and 
request that they always communicate with these neighbors. If each server has 
at least one neighbor supplied to it, status information may then propagate 
through a neighbor to hosts that are not (possibly) directly neighbors. If the 
server is able to support networks that provide a broadcast capability, as well as 
those that do not, ttien networks with an arbitrary topology may share status 
information. 
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NOTE 



Programmers must be concerned about loops, however. If a host is con- 
nected to multiple networks, it will receive status information from itself. This 
can lead to an endless, wasteful, exchange of information. 



It is important that software operating in a distributed environment not have 
any site-dependent information compiled into it. This would require a separate 
copy of the server at each host and make maintenance a severe headache. The 
UNIX system attempts to isolate host-specific information from applications by 
providing system calls that return the necessary information. (An example of 
such a system call is the get hostname (3N) call that returns the host's official 
name.) The ioctl () call allows you to find the collection of networks to 
which a host is directly connected. Further, a local network broadcasting 
mechanism has been implemented at the socket level. Combining these two 
features allows a process to broadcast on any directly connected local network 
that supports the notion of broadcasting in a site independent manner. This 
solves the problem of deciding how to propagate status information with rwho, 
or more generally in broadcasting. Such status information is broadcast to con- 
nected networks at the socket level, where the connected networks have been 
obtained via the appropriate ioctl () calls. The specifics of such broadcastings 
are complex, however, and will be covered in the "Advanced Topics" section 
below. 
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Several facilities have yet to be discussed. For most programmers, the mechan- 
isms already described will suffice in building distributed applications. How- 
ever, others will find the need to use some of the features that we consider in 
this section. 



Out Of Band Data 

The stream socket abstraction includes the notion of out of band data. Out of 
band data is a logically indef>endent transmission channel associated with each 
pair of connected stream sockets. Out of band data is delivered to the user 
independently of normal data. The abstraction defines that the out of band data 
facilities must support the reliable delivery of at least one out of band message 
at a time. This message may contain at least one byte of data, and at least one 
message may be pending delivery to the user at any one time. For communica- 
tions protocols (such as TCP) that support only in-band signaling (i.e., the urgent 
data is delivered in sequence with the normal data), the system normally 
extracts the data from the normal data stream and stores it separately. This 
allows users to choose between receiving the urgent data in order and receiving 
it out of sequence without having to buffer all the intervening data. It is possi- 
ble to "peek" (via MSG_PEEK) at out of band data. If the socket has a process 
group, a SIGURG signal is generated when the protocol is notified of its 
existence. A process can set the process group or process id to be informed by 
the SIGURG signal via the appropriate fcntl () call, as described below for 
SIGIO. If multiple sockets may have out of band data awaiting delivery, a 
select 0 call for exceptional conditions may be used to determine those sock- 
ets with such data pending. Neither the signal nor the select show the arrival of 
the out-of-band data, but only notification that it is pending. 

In addition to the information passed, a logical mark is placed in the data 
stream to specify the point at which the out of band data was sent. The remote 
login and remote shell applications use this facility to propagate signals between 
client and server processes. When a signal flushes any pending output from the 
remote process(es), all data up to the mark in the data stream is discarded. 

To send an out of band message the MSG_OOB flag is supplied to a send ( ) or 
sendto 0 calls, while to receive out of band data MSG_OOB should be specified 
when doing a recvf rem () orrecvO call (unless out of band data is taken in 
line, in which case the MSG_CX)B flag is not needed). To find out if the read 
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pointer is currently pointing at the mark in the data stream, the SIOCATMARK 
ioctl is provided: 

ioctl(s, SIOCATMARK, &yes) ; 

If yes is 1 on return, the next read will return data after the mark. Otherwise 
(assuming out of band data has arrived), the next read will provide data sent by 
the client before transmission of the out of band signal. The routine used in the 
remote login process to flush output on receipt of an interrupt or quit signal is 
shown in the following example. This code reads the normal data up to the 
mark (to discard it), then reads the out-of-band byte. 



Figure 3-10: Flushing Terminai I/O on Receipt of Out Of Band Data 



fincXucte <:ays/ic»ta-h> 



Int oat » FMWCTE; 
char wast&tBl]FSl2]; 
XrAr marlc; 

Z*^ flu^h local terminal output */ 
ioc?ua. TiOCEXUSH^ (d^y *)<oat>; 
for i 

it (ioctl (2fiin, ^OCMSARK, tmark) < 0) { 

if (mark) 

break; 

(void) xea^irm, waete, aizeof iwaste) ; 
if Crecv(rati, Amark, 1, MSGJDOB) < 0) { 
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A process may also read or peek at the out-of-band data without first reading 
up to the mark. This is more difficult when the underlying protocol delivers the 
urgent data in-band with the normal data, and only sends notification of its 
presence ahead of time (e.g., the TCP protocol used to provide socket streams in 
the Internet domain). With such protocols, the out-of-band byte may not yet 
have arrived when a recv () is done with the MSG_OOB flag. In that case, the 
call will return an error of EWOULDBLOCK. Worse, there may be enough in-band 
data in the input buffer that normal flow control prevents the peer from sending 
the urgent data until the buffer is cleared. The process must then read enough 
of the queued data before the urgent data may be delivered. 

Certain programs that use multiple bytes of urgent data and must handle multi- 
ple urgent signals (e.g., telnet (1)) need to retain the position of urgent data 
within the socket stream. This treatment is available as a socket-level option, 
SO_OOBINLINE; see setsockopt(3N) for usage. With this option, the position 
of urgent data (the "mark") is retained, but the urgent data immediately follows 
the mark within the normal data stream returned without the MSG_OOB flag. 
Reception of multiple urgent indications causes the mark to move, but no out- 
of-band data are lost. 



Non-Blocking Sockets 

It is occasionally convenient to make use of sockets that do not block; that is, 
I/O requests that cannot complete immediately and would therefore cause the 
process to be suspended awaiting completion are not executed, and an error 
code is returned. Once a socket has been created via the socket ( ) call, it may 
be marked as non-blocking by f cntl () as follows: 
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lincXiade <Xx3ntX.h> 
int 5; 

If <£Gntl(3r FJSETFL, FNDELAYy < 0) 
B3Cit(l); 

illlllllllll^ 



When perfonning non-blocking I/O on sockets, one must be careful to check for 
the error EWOULDBLOCK (stored in the global variable errno), which occurs 
when an operation would normally block, but the socket it was performed on is 
marked as non-blocking. In particular, accept () , connect () , send {) , 
recv 0 , read () , and write () can all return EWOULDBLOCK, and processes 
should be prepared to deal with such return codes. If an operation such as a 
send () cannot be done in its entirety, but partial writes are sensible (for exam- 
ple, when using a stream socket), the data that can be sent immediately will be 
processed, and the return value will show the amount actually sent. 

Interrupt Driven Socket I/O 

The SIGIO signal allows a process to be notified via a signal when a socket (or 
more generally, a file descriptor) has data waiting to be read. Use of the SIGIO 
facility requires three steps: First, the process must set up a SIGIO signal 
handler by use of the signal 0 orsigvecO calls. Second, it must set the 
process id or process group id that is to receive notification of pending input to 
its own process id, or the process group id of its process group (note that the 
default process group of a socket is group zero). This can be done by using a 
fcntlO call. Third, it must enable asynchronous notification of pending I/O 
requests with another fcntl () call. Sample code to allow a given process to 
receive information on pending I/O requests as they occur for a socket s is 
given in Figure 3-11 With the addition of a handler for SIGURG, this code can 
also be used to prepare for receipt of SIGURG signals. 



















'J 
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Figure 3-11: Use of Asynchronous Notification of I/O Requests 



lincaude <f<sntl.h> 

int ioJiandl^O;^ 
signal (SICJIO, lqJu«i<Jler) ; 

/* Set the process reoelving^ SIGIO/SIQORG signals to us» */ 

it (£6ntl<a^ t^SStJxm, ^^tpidO) < 0> { 
perrar(''f<?ntl F_SETCIWN«)/ 

/* Allo»f receipt of Asynchronous 1/0 signals. */ 

if (fcntKs^ FJ5ETFL, PA3YNC> < 0> { 

pe^rorCfcntl F^SBtgl,, FAS^fC**); 
exita); 

iliiiiiiiiiiiiiiiiiiiiiiiilli^ 



Signals and Process Groups 

Because of the existence of the SIGURG and SIGIO signals, each socket has an 
associated process number, just as is done for terminals. This value is initialized 
to zero, but may be redefined at a later time with the F_SETOWN f cntl () , such 
as was done in the code above for SIGIO. 

To set the socket's process id for signals, positive arguments should be given to 
the f cntl 0 call. To set the socket's process group for signals, negative argu- 
ments should be passed to f cntl () . 

The only acceptable arguments to these system calls are the caller's process id or 
a negative process group having the same absolute value as the caller's process 
id (the process must be the process group leader of its own process group). 
Therefore, the only allowed recipient of SIGURG and SIGIO signals is the cal- 
ling process. 
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Note that the process number shows either the associated process id or the asso- 
ciated process group; it is impossible to specify both at the same time. A similar 
f cntl 0 , F_GETOWN, is available for determining the current process number 
of a socket. 

Note that the receipt of SIGURG and SIGIO can also be enabled by using the 
ioctl 0 call to assign the socket to the user's process group: 



/* oobdata Is the out-qf-band data handling routine *f 
Signal (SXOOE^, oobdata); 

int pid - -<retpld(>; 

If (ioctl (client, SIOCBPGRP, (char *)fipld) < 0) t 
perrorCloctl; SXOCSPOWP"); 



Another signal that is useful when building server processes is SIGCHLD. This 
signal is delivered to a process when any child processes have changed state. 
Normally servers use the signal to "reap" child processes that have exited 
without explicitly awaiting their termination or periodically polling for exit 
status. For example, the remote login server loop shown in Figure 3-7 may be 
augmented as follows: 
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Figure 3-12: Use of the SIGCHLD Signal 

r ^ 

Ant leaperO; 

signal (3ICICHII3r z»aper}; 

int g, 2w ** 3l2©of from; 



^ « accept (f/ (struct Bockaddr *>fifroin, &len,>; 
(g < 0) { 

it {&ttti<y film) 

syslog l(LOG^£SR, ^rlogixxi: accept^ %m"); 

continue; 

llllllllllll;^^ 

♦include <wait,h> 
zeaperO 

int status; 



w*tile (wait<««t«tU3) > 0) 
continue; 



If the parent server process fails to reap its children, several zombie processes 
may be created. 



Selecting Specific Protocols 

If the third argument to the socket () call is 0, socket () will select a default 
protocol to use with the returned socket of the type requested. The default pro- 
tocol is usually correct, and alternate choices are not usually available. How- 
ever, when using "raw" sockets to communicate directly with lower-level proto- 
cols or hardware interfaces, the protocol argument may be important for setting 
up demultiplexing. For example, raw sockets in the Internet domain may be 
used to implement a new protocol above IP, and the socket will receive packets 
only for the protocol specified. To obtain a particular protocol one determines 
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the protocol number as defined within the protocol domain. For the Internet 
domain one may use one of the library routines discussed in the "Supporting 
Routines" section above, such as getprotobyname () : 



llndude <5y8/t;^pea.h> 
♦inclucle <5y3/»oc}tet,h> 
llAclijde •4ietitiet/ln.h> 
#inqlud9 <aiBti6tf*h> 

3 - socket WJQI&'r, SOCKJSJPBEaM^ psH>PJP¥Oto)[J 



This would result in a socket s using a stream based connection, but with pro- 
tocol type of newtcp instead of the default top. 



Address Binding 

As was mentioned in the "Basics" section, binding addresses to sockets in the 
Internet domain can be complex. As a brief reminder, these associations are 
composed of local and foreign addresses, and local and foreign ports. Port 
numbers are allocated out of separate spaces, one for each system and one for 
each domain on that system. Tlu-ough the bind {) system call, a process may 
specify half of an association, the <local address, local port> part, while the con- 
nect () and accept 0 primitives are used to complete a sockefs association 
by specifying the <foreign address, foreign port> part. Since the association is 
created in two steps the association uniqueness requirement mentioned previ- 
ously could be violated unless care is taken. Further, it is unrealistic to expect 
user programs always to know proper values to use for the local address and 
local port since a host may reside on multiple networks and the set of allocated 
port numbers is not directly accessible to a user. 

To simplify local address binding in the Internet domain the notion of a wild- 
card address has been provided. When an address is specified as INADDR_ANY 
(a manifest constant defined in <netinet/in . h>), the system interprets the 
address as any valid address. For example, to bind a specific port number to a 
socket, but leave the local address unspecified, the following code might be 
used: 



3-48 



Programmer's Guide: Networking Interfaces 



Advanced Topics 



lincXude <l5y5/typ©».h> 
|ln&lud6 <h6tiii6t/ltt.h> 

n * socket (AP^JNET, SOCKSTREfiM^ 0); 

^in^^ixi^addr^s^addr «• htonl (INADDR_ANY} ; 

aijv-alnjport - htons (MXPORT) ; 

bind(d, <5tzi2ct soclcaddr *) £ain, aizeof sin); 



Sockets with wildcarded local addresses may receive messages directed to the 
specified port number, and sent to any of the possible addresses assigned to a 
host. For example, if a host has addresses 128.32.0.4 and 10.0.0.78, and a socket 
is bound as above, the process will be able to accept connection requests that 
are addressed to 128.32.0.4 or 10.0.0.78. If a server process wished to only allow 
hosts on a given network connect to it, it would bind the address of the host on 
the appropriate network. 

In a similar fashion, a local port may be left unspecified (specified as zero), in 
which case the system will select an appropriate port number for it. For exam- 
ple, to bind a specific local address to a socket, but to leave the local port 
number unspecified: 



hp » gethoatbyname (hostname) ; 
if (hp — NUIX) { 

llllllllllllllli 

ineincpy<<char *) ain.ain_addr, hp->h_addr, hp->h_length) ; 

sln.sin_pQrt « htana<0); 

bind (5/ <dtruct Bod^ddc ^ain^ aisseof ain); 



The system selects the local port number based on two criteria. The first is that 
Internet ports below IPPORT_RESERVED (1024) are reserved for privileged 
users (i.e., the super user); Internet ports above IPPORT_USERRESERVED 
(5000) are reserved for non-privileged servers. The second is that the port 
number is not currently bound to some other socket. To find a free Internet 
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port number in the privileged range the rresvport () library routine may be 
used as follows to return a stream socket in with a privileged port number: 

Int Iport * IPPORT^RESERVED - X; 
Int s; 

a rretdvport <*Xpott)[ ? 
If <9 < 0> { 

U (ermo EftCAlN) 

f printf (stderl:, "socket: all ports In use\il^); 

else 

: J 

This restriction was placed on port allocation to allow processes executing in a 
"secure" environment to do authentication based on the originating address and 
port number. For example, the r login (1) command allows users to log in 
across a network without being asked for a password, provided that two condi- 
tions are met: First, the name of the system the user is logging in from must be 
in the file /etc/hosts . equiv on the system being logged in to (or the system 
name and the user name inust be in the user's . rhosts file in the user's home 
directory). Second, the user's rlogin process must come from a privileged port 
on the machine from which the user is logging in. The port number and net- 
work address of the machine from which the user is logging in can be deter- 
mined either from the accept () call (the from result), or the getpeername () 
call. 

In certain cases the algorithm used by the system in selecting fX)rt numbers is 
unsuitable for an application. This is because associations are created in a two 
step process. For example, the Internet file transfer protocol, FTP, specifies that 
data connections must always originate from the same local port. However, 
duplicate associations are avoided by connecting to different foreign ports. In 
this situation the system would disallow binding the same local address and 
port number to a socket if a previous data connection's socket still existed. To 
override the default port selection algorithm, an option call must be performed 
before address binding: 
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detBOC)copt(d, SOt^SCCKBt, SOJNBUSBADDR^ fKXi^ sizdof on); 

With the above call, local addresses may be bound that are already in use. This 
does not violate the uniqueness requirement as the system still checks at connect 
time to be sure any other sockets with the same local address and port do not 
have the same foreign address and port. If the association already exists, the 
error EADDRINUSE is returned. 



Broadcasting and Determining Networic Configuration 

By using a datagram socket, it is possible to send broadcast packets on many 
networks connected to the system. The network itself must support broadcast; 
the system provides no simulation of broadcast in software. Broadcast messages 
can place a high load on a network since they force every host on the network 
to service them. Consequently, the ability to send broadcast packets has been 
limited to sockets that are explicitly marked as allowing broadcasting. Broad- 
cast is tjrpically used for one of two reasons: it is desired to find a resource on a 
local network without prior knowledge of its address, or important functions 
such as routing require that information be sent to all accessible neighbors. 

To send a broadcast message, a datagram socket should be created: 

s » socket (AF_INET, SOCK_DGRAM, 0) ; 
The socket is marked as allowing broadcasting, 

int on - 1; 

setsockopt (Sr SOL_SOCKET, SO__BROADCAST, &on, sizeof on) ; 
and at least a port number should be bound to the socket: 
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aln . SiflT^Kadr , S^iddr"- htbhl (HIADDRANY) ; 
sin.sinjxxrt * htons (WfPORT) ; 
bind(d« (stxiiet «od)cadar ^) i^sin^ diz^f dixx) ; 

v 

The destination address of the message to be broadcast depends on the 
network(s) on which the message is to be broadcast. The Internet domain sup- 
ports a shorthand notation for broadcast on the local network, the address 
INADDR_BROADCAST (defined in <netinet/in. h>. To determine the list of 
addresses for all reachable neighbors requires knowledge of the networks to 
which the host is connected. Since this information should be obtained in a 
host-independent fashion and may be impossible to derive, the UNIX system 
provides a method of retrieving this information from the system data struc- 
tures. The SIOCGIFCONF ioctl call returns the interface configuration of a 
host as a single if conf structure; this structure contains a "data area" that is 
made up of an array of if req structures, one for each address domain sup- 
ported by each network interface to which the host is connected. These struc- 
tures are defined in <net /if . h> as follows: 



J 
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/* it name, *«nO** */ 



dtxuct ifretj \ 

union ( 

9truct scxikaddr Ifrujodclr; 

Struct aocka<JcU: ifiujistaddr; 

Ch^ lf£Ujc»iaitett£tl^l21; /* othto If n^ V 

struct PQckacldr ifruJsrpaclaclcU:; 
Short ifru^flags; 

Int ifrujtetrie; 
char ifrujjataiaj; /* interface depwtent data */ 

char lfrajenaddrC€3; 
} ifr^lfru; 

#dafln6 IfiMMkir ifr_ifztt.lfzUjKld£ addtdSai V 

Idaflne ifrjjstaddlr Itr^lfi^^frujAstadar /* othar end of p-tO-p link */ 

#defin6 ifr_ott»me jUTrjLfru.ifrujsnamei /♦ oth^r if name */ 

#de£ine ifrbroadaddr if r_if zu . if rujsroadaddr broadcast addtesS */ 

fdefine ifr/lags ifr2ifxu,ifru_flag» /* flags */ 

♦dafine ifrjoetric ifr_ifru.ifruj)«atric /* matric ♦/ 

♦define ifrjdata ifr_ifru.ifru _data /* for use by interface */ 

♦define ifr_enaddr ifr ifiu,ifru_enadcjr /* etheznet address */ 



The call that obtains the interface configuration is: 



struct ifconf ifc; 
char buffBUPSIZ]; 

ifc.ifc_len m sizeof buf; 

ifcifcjjuf - buf; 

if (i0ctl<3r StCQSI^Ct^, 



} 



(chat *} 4ifc> < 0) { 



After this call buf will contain a list of if req structures, one for each network 
to which the host is connected. These structures will be ordered first by inter- 
face name and then by supported address families, ifc . if c_len will have 
been modified to reflect the number of bytes used by the if req structures. 
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For each structure there exists a set of "interface flags" that tell whether the net- 
work corresponding to that interface is up or down, point to point or broadcast, 
etc. The SIOCGIFFLAGS ioctl retrieves these flags for an interface specified 
by an if req structure as follows: 



struct Xtt&q *i£r; 

iiiiiiiiiiiiliiiiiiiiiii 

^ W& m^t b6 ti^ful th&t 60n*t Use an ititerface 

* davote^ t^O an address ckxaain other than those Intended 

ijiiiiiiiiiiiiiiiliiiiliiiiii 

If (l£r->l£radd£.ia_£amUy J^r^lUfiH) 
contini^e; 

if (ioctl (s^ SIOCJGimAGS, (char *) ifr) < 0) { 

* Skip boring cases 

iiiiiiiiiiiiiiii 

if (afr->ifr_flags £ IfSjO^) 0 {} 
(ifi>-Mfr_flags i. IEPJWX»BACK) jj 
(ifr-'>ifr_flags ^ 

aFF_BRDaScAST J IB^'_^POI»TOPQINT) ) — O 

continue; 



Once the flags have been obtained, the broadcast address must be obtained. 
With broadcast networks this is done via the SIOCGIFBRDADDR ioctl, while 
for point-to-point networks the address of the destination host is obtained with 
SIOCGIFDSTADDR. 
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dtxnd: dockaddr ddt; 



if "(loctX(», siiSc»lFDS1«ta)R^ (char ♦)[ Aft) < 0> I 



^Izeof If r->if rja?itaddr) ; 
} ^lae If <ifr-!>lfr_f ld(gd « lFF_BliiADCAS'Il> { 

if (ioctl(i, SlOOGlB'BraADtJR^ (diar *) ifr) < 0) { 



liiiiiiiiiiiiiiiiiiiiiiiiiiiii^^ 

ineincpy ( (<?har *) id^t, (char fiifr->lfrbroadadcir, 
alzeof If 2»if r broa<aacar) ; 



After the appropriate ioctl () s have obtained the broadcast or destination 
address (now in dst), the sendto () call may be used: 

sendto(s, buf^ buflen, 0, (struct sockaddr *)&dst, 
sizeof dst) ; 

In the above loop one sendto {) occurs for every interface to which the host is 
connected that supports the notion of broadcast or point-to-point addressing. If 
a process only wished to send broadcast messages on a given network, code 
similar to that outlined above would be used, but the loop would need to find 
the correct destination address. 

Received broadcast messages contain the sender's address and port, as datagram 
sockets are bound before a message is allowed to go out. 



Socket Options 

It is possible to set and get several options on sockets via the setsockopt () 
and getsockopt () system calls. TTiese options include such things as marking 
a socket for broadcasting, not to route, to linger on close, etc. The general forms 
of the calls are: 

setsockopt (s, level, optname, optval, optlen) ; 
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and 

getsockopt (s, level, optname, optval, optlen) ; 

The parameters to the calls are as follows: s is the socket on which the option is 
to be applied, level specifies the protocol layer on which the option is to be 
applied; usually this is tihe "socket level/' indicated by the symbolic constant 
SOL_SOCKET, defined in <sys/ socket . h> . The option is specified in 
opt name, and is a symbolic constant also defined in <sys/socket .h>. 
optval and optlen point to the value of the option (usually, whether the 
option is to be turned on or off), and the length of the value of the option, 
respectively. For getsockopt () , optlen is a value-result parameter, initially 
set to the size of the storage area pointed to by optval, and modified on return 
to show the amount of storage used. 

An example should help clarify things. It is sometimes useful to determine the 
type (e.g., stream, datagram, etc.) of an existing socket; programs invoked by 
inetd (described below) may need to do this task using the SO_TYPE socket 
option and the getsockopt 0 call: 



r 








fincXudet <3ys/t:^B,h> 
♦include <sys/socket.h> 
















3l2e - 3iaeof (int) ; 








if (getsoqIc<^tt9r SQLJSOCKET^ sq. 

iiiiliiiiiiiiiiiliiiiil^ 

V 










J 



After the getsockopt () call, type will be set to the value of the socket tj^e, 
as defined in <sys/ socket . h>. If, for example, the socket were a datagram 
socket, type would have the value corresponding to SOCK_DGRAM. 
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inetd 

One of the daemons provided with the UNIX sytem is inetd, the so called 
"Internet super-server/' inetd is invoked at boot time by the Service Access 
Controller, and determines the services for which it is to listen from the file 
/etc/inetd. conf . Once this information has been read and a pristine 
environment created, inetd proceeds to create one socket for each service it is 
to listen for, binding the appropriate port number to each socket. 

inetd then performs a select () on all these sockets for read availability, 
waiting for somebody wishing a connection to the service corresponding to that 
socket, inetd then performs an accept () on the socket in question, 
fork 0 s, dup () s the new socket to file descriptors 0 and 1 (stdin and stdout), 
closes other open file descriptors, and exec () s the appropriate server. 

Servers making use of inetd are considerably simplified, as inetd takes care 
of most of the communication work required in establishing a connection. The 
server invoked by inetd expects the socket connected to its client to be on file 
descriptors 0 and 1, and may immediately do operations such as read () , 
write { ) , send ( ) , or recv ( ) . Indeed, servers may use buffered I/O as pro- 
vided by the stdio conventions, as long as they remember to use f flush {) 
when appropriate. 

One call that may be of interest to individuals writing servers to be invoked by 
inetd is the getpeername ( ) call, which returns the address of the peer (pro- 
cess) connected on the other end of the socket. For example, to log the Internet 
address in "dot notation" (e.g., "128.32.0.4") of a client connected to a server 
under inetd, the following code might be used: 
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i 

jSttuct dodcaddrjln xamt 
int ndmelen <• aiteot hame; 

if (^^tpeemameCO, ! 
^stmct Bockaddr *>&iiaree, finam^len) < 0) { 
SYSlog(L0GJ5E»/ "^getpeemaroe: %»•*>; 
exitd); 

) el9e 

inet^ntoa (naroa . dliljaiddr) ) ;! 

v" J 

While the get peer name () call is especially useful when writing programs to 
run with inetd, it can be used under other circumstances. 
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This chapter provides an introduction to the issues involved in porting a sockets 
application to TLI and includes notes on the differences between BSD sockets 
and System V Release 4 sockets that programmers must be aware of. Although 
existing sockets applications can be rewritten for TLI relatively easily, such ports 
are not necessary for sockets applications that are to run only over TCP/IP or 
UDP/IP networks. However, TLI is the preferred programming interface for 
accessing transport services and it is recommended that programmers writing 
new applications for System V Release 4 use TLI. 

Both TLI and sockets routines are defined in terms of communications paths 
identified by file descriptors. These file descriptors are known as "transport 
endpoints" for TLI and as "sockets" for the socket interface. In most cases, 
there are parallel routines for each transport function. For example, the TLI rou- 
tine tjopenO returns a file descriptor that identifies a transport endpoint; the 
routine socket () returns a file descriptor that identifies a socket. Table 4-1 at 
the end of this section shows the parallels among TLI and sockets interface rou- 
tines. 

This chapter will highlight the areas in which there is no direct correspondence 
between TLI and sockets routines. The examples will first show code that uses 
the socket interface and then show how to rewrite the program using TLI. 

The last section of the chapter documents differences between System V Release 
4 sockets and BSD sockets. Programmers must be aware of these differences 
before moving BSD sockets applications to System V Release 4. 

System V socket calls are implemented as library routines. Application pro- 
grams that use sockets should be compiled and linked with socket libraries: 
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Connection Mode 

Both TLI and sockets support two distinct types of service: connection oriented 
and connectionless. 

Establishing Socicet Connections: Client Code 

When creating a socket, the type of service must be specified (for example, 
SOCK_STREAM, SOCK_DGRAM, SOCK_RAW). The service type determines 
whether connection-oriented or connectionless semantics are used. For a simple 
example of connection establishment, consider the client side of a stream- 
oriented application, as in Figure 4-1. It must initiate a connection by first creat- 
ing a stream socket and then using the connect () call to establish communica- 
tion with a preexisting socket on a server machine. 



Figure 4-1 : Ciient Side of Stream-Oriented Appiication 

#lnclude <sys /types. h> 
♦include <3ys/socket,h> 
♦include <netinet/in.h> 
♦include <netdb.h> 
♦include <dtdio.h> 

malnCarigc/ argv) 

int argc; 
char ^axgvfj; 

int seek; 

Struct sockaddr^in server; 
struct hostent *hpr *^thostbyna>ne<) ; 
struct servent *sp, ^^etT^rr^ynameO ; 

/* create socket 

sock socket (AF_INET, i$OCXL_STSElM, 0); 
if (50Ck < 0> { ^ 

perrorC^opening stream socket"); 

exit(l); 

/* OOTinect socket using name specified by conitiand line */ 
server. sin_^family - AF_INET; 
hp gethostbyname (argv 11] ) ; 

v_ . . 

(continued on next page ) 
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Figure 4-1: Client Side of Stream-Oriented Application (continued) 



it (J^ — 0) ( 

fprlntf {atdfttt, '♦%dt OtitoiOimi hdit\tt*, aiigvll]); 

if (1^ D> { 

iiiiiiiiiiil^ 

if (connect (jiock^ (struct sockaaitr *)4«0rver, 
5iasec>f derver ) < Q) { 

perror ('•connecting stiearo ^o^et"); 
exlt(l); 



Notice the calls to get host byname () and getservbyname () . These are the 
socket-oriented network directory services described under "Socket-Based 
Datagrams/' They take a host and service name, respectively, and retum the 
host network address and the service port. The service port number can be 
thought of as a machine-specific service address. Certain well-known services 
are assumed to have specific TCP port numbers in the l-to-1023 range. Some 
applications hard code these port numbers rather than using get- 
servbyname () . 

When porting sockets applications to TLI, calls to gethostbyname () and get- 
servbyname 0 , as well as hard-coded TCP port numbers, should be replaced 
by calls to the netdir_getbyname {) routine. 

If the target socket exists and is prepared to handle a connection, the connection 
will complete successfully and the program can begin to send messages. Mes- 
sages will be delivered in order without message boundaries. The connection is 
destroyed when both s(x:kets are closed. 
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Some transports hold the connection open briefly in case more data are 
NOTE sent. The user may also have directed the system to wait. For more infor- 
mation, see the discussion of the S0_LINGER optbn on the 
I getsockopt(3N) manual page. 



Establishing TLI Connections: Client Code 

The TLI connection mode transport service is also circuit (stream) oriented, ena- 
bling data to be transferred over an established connection in a reliable, 
sequenced manner. Typical TLI client code is shown in Figure 4-2. 



Figure 4-2: TLI Client Code 

♦Includa <n.«tdtr,h> 
linqliide •Oi^t^Qnficf.h> 



6Xt^ Iht tjdtrxiio; 



mini) 

int f d; 

atxuct tietconf ig *tkCon£i 
void *handlep; 

* seletct an appropriate network 

it ((handlep ^ aetnetpathO) — WJLL) ( 

ncj»rror ("Error In inltlaXlttng networks'*); 
exlt(l>; 

* try dia transports until finding one that watches 

* the users stated preferences 

vhilA ((nconf « getnetpath (handl^) > l» NOLL) { 
If (l»Conf->nc_»einantiC5 *- NCJEP3:jX>TS) 

V J 

(continued on next page) 
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Figure 4-2: TLI Client Code (continued ) 



i£ (iKJonf — » NOLL) ( 

fprlntf (stderr, *no t«m5porta avaiXabX^Nn**); 
exit (1) ; 

;;|||;|||||||||;|;;;||||| 

if ( (f d - tL.open (ncon£->iiGjctevice, 0_BDWR, NULL) y < 0) { 
tjw:ror(*tjDpen fallecS**); 



it (tj>itid(fd, NULL^ NULL) < 0) { 
terror(*«tJ)±nci failed"); 
€«it(3); 

€aK3netpath (handlep) ; 



Network selection is used by TLI applications to find the device filename associ- 
ated with the requested transport protocol. The device filename that matches 
the protocol is passed to t_open {) . t__open () then returns a file descriptor 
that identifies a new transport endpoint, and optionally (by way of its third 
argument), the default characteristics of the transport provider associated with 
that endpoint (and indirectly specified by the first argument). t_bind{) then 
binds the new transport endpoint to the transport address contained in its 
second argument. The typical client doesn't care what its own address is 
because no other process will try to access it. The second and third arguments 
in the example are therefore NULL. 
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Establishing Soclcet Connections: Server Code 

Connection establishment for a server process is slightly different. The process 
must bind itself to an address and wait for clients to connect to it. Figure 4-3 
shows how a sockets server is bound to its known address: 



Figure 4-3: Socicets Server Code 



fiftcludb <dyd/dOdfadt.h> 

♦include <stdl0.h> 
Idef ins SRV_PC»T 2 
jnain (argc, argvj 



int 

char 

{ 



argc; 
*^a3?gvt] ; 

int 

struct Bockaddrjln server; 

int 

Char 

/* <rceate socket */ 



sock; 

msgsock; 
bufCBOFStZJ; 



sock • socket <AS*_tKfi!t, ISOCKJSTSUSI^, Q); 
if (sock < d> { 

percor{**o{«hi»!g dtteiatt BOcket**>; 

exita>,< 

/* name socket ♦/ 

sersey.sln^fwftlly * APJOTT 
seijver.sift^ddr.sjiiddtr** Mffl^SMtJdKtJf^* 
server. sin_port * SRVPORT; 

if (bind(sock^ (struct sodcadar *)*S6rw>r>^ sizeof server) < 0) { 
perzorC*blndij!)9 strd^ dddcet^>; 
exit (2); 

the server now does a listen and accept 



In the example, the server explicitly asks to be bound to port SRV_PORT. 
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Establishing TLI Connections: Server Code 

The equivalent code for a TLI server process is shown in Figure 4-4. 
Figure 4-4: TLI Server Code 



fiiieludte <£cstttl.h> 
linclixlte <netCQn£ig<fa> 
flneOudd <asit<3ax,ii> 

main (argc/ argv> 



int 



♦argfvll; 

struct ndJiOstsexvd hostaer\r; 

int ^ fd; 

chsx buf(B0FSI2J; 

struct netocxifig ^conf; 

Struct tj>ln(i *bind; 

void *hai!idlep; 

extern int tjezxno; 

if ( arge J* 3 ) J 

fprlntf (stderr^ "tJSaGE; %s host serviceVn", argvlQl); 

hostserv.hjiost * argvm; 

if iQimSOm ^ aetnetpathO) — l!^tnx) { 
ll<Sj>6(ttorC'setnetpath") : 

llliijiiljiilllllllllll 

* select m a;^^;riate transport and 
^ addtBii for tmdt^ ho»t/d^£vi<:ad: 

lAkil^ ((ncoiif - getnetpath(handlep)) 1- KUIX) { 
If (ne6n£->nG_s€9nanticS NCJTPIJDTS) 
break; 



(continued on next page ) 
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Figure 4-4: TLI Server Code (continued ) 



If (nconf NULL> { 

f pirlntf (stdarr, "no connection modb tJ^ansportXn") ; 



) 



if ((fd * tjopen(nconf-->nojaevicei, OJ9m, ITOL)J < 0) ( 

f prlntf (stdsTTr "unable tQ qp^n %9\n'*« nconf -^>nqjdevioe^ ; 
exit (4); 

iiiiiiiiliiiiiiiiiiiiiiiiii 

en<Jnetpath (handlep> ; 

if Ubind • (itnlct tbifid *)t_ano<s{£d, tJAm>, tjKtt.)) HtttJC> | 
tjerroa?(*t^alloc of tj&ind aitrqoture failed") ? 
e5cit(5); 

iiiiiliiiiiiiiiiiiiiiiillii 



* for sixrplicity in thi3 example, assume the 

* addteds is an integer 



bind->addr< len «• sizeof^int); 
*(int *)bind->adclr.buf - SRVMS^R; 

/* 2nd arcf mjLL -> bind to any address */ 

if (t_bihd<fd, bind, bind) < 0) { 
t^errorCtJ^ind failed"); 
exit (6); 

/* l*as the CQi*ect Jtddress bound? */ 

if <*(int *)bind->addr.buf r- SRVADDR) { 

tjeixor(**tj5ind bound wrong address''); 
exit (7); 



/* the server now does a list^ and accept */ 
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The examples show two significant differences between sockets and TLI. First, 
since TLI server applications work over any transport provider, they use the 
Network Selection and Name-to- Address Mapping features in order to be proto- 
col independent; sockets applications use fixed addresses. 

A second difference is in the behavior of the TLI and sockets bind routines when 
an address is invalid or unavailable. The sockets bogad ( ) routine fails. The TLI 
t_bind ( ) routine may bind to another address instead. For this reason, TLI 
servers should check that the address returned by t_bind () as its third argu- 
ment is correct. 



Connectionless Mode 

Connectionless-mode transport services, in contrast to connection-oriented ser- 
vices, are message-oriented and support transfer in self-contained units 
(datagrams) with no necessary logical relationship to each other. Sockets and 
TLI both provide connectionless-mode service. 

All the information required to deliver a datagram (for example, a destination 
address) is presented to the transport provider, together with the data to be 
transmitted, in a single service access. A given service access need not relate to 
any other service access. Each unit of data transmitted is entirely self-contained, 
and can be independently routed by the transport provider. 

Socket-Based Datagrams 

The differences between socket library datagrams and the connectionless service 
provided by TLI parallel the differences between sockets and TLI connection- 
oriented service described above. Figure 4-5 gives the code necessary to send 
an Internet domain datagram to a receiver whose host and service names are 
given as command line arguments. 
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Figure 4-5: Sending Internet Domain Datagram 



#incJTjde <8ys/types.h> 
#lnelitde <»y»/docJk»t.h> 
finclude '(^tlnet/iii.h> 

fincXttde <stdlo«h> 

#<Jef±i» mch "Xt waa the beat of tiniea* 



was the worst of tim&«: 



* 3!he foxiii of the command line is: 

* cHgramsend hostnama flezviqenanis 



attain (ar^Cf argv) 

char *axgvn; 



Struct sezvent *spf ♦getservbynameO; 
int sock; 

struct sockaddr^in nama; 

struct hostent *hp, ^gethostbynameO; 

create socket on which to send */ 
sock w socket <AP_IHET, SOOHJ^Oem, 0); 
if <aocJt < 0) {'^ 

perror(**opening datagram sockef^; 

exlt(X>; 

||||||||||;|||||||||| 

* Find the socket to send to, gethostbyname () returns a structure 
^ including the netwcork address of the specified host^ port 

* m»id3e^ is taken trm the coirmand line. 

Illlllillllillllllllll 

hp * gethostbyname (argv [ 1] ) ; 
if (hp Q) { 

f printf (stderr, «%s; unkno%in hostVn", argv[l]); 

e3dt«>; 

mernqsyUohar *) finarae . sin^addr, (char *)hp->h^addry 

hp~:*_length); 
nanie.sln_famlly AF^INET; 
sp - get servbyname (argv [ 2 ] , "top" > ; 
tf (sp 0) ( 

f printf <stderr, "%s; unknown. serviceXn*^, argvUJ); 

exit (3); 



(continued on next page) 
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Figure 4-5: Sending Internet Domain Datagram (continued ) 



i* send R^ssage V 

if (8endto(30ck, tikiSk, t\x^t l>{lt^ , 0, 

(struct sodcaddr *)&nanie, 9^z^t name) < 0) 

«xit(0>/ 



The program looks up the host address and the service port (both given on the 
command hne) by calling gethostbyname () and getservbyname () . The 
host network address and service port number are in the structures returned by 
these two library routines. They are copied into the structure that specifies the 
destination of the message. 

TLI Datagrams 

TLI connectionless service is functionally similar to sockets datagram service. 
The sockets address management routines gethostbyname () and get- 
servbyname () are replaced by netdir_getbyname 0 for both connection- 
oriented and connectionless service. 

The TLI code in Figure 4-6 sends a datagram to a receiver whose host and ser- 
vice names are given on the conunand line: 
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Figure 4-6: TLI Datagram Code 



♦incliade <st<J±o.h> 
lintilude <fcntl.h> 
#include <aetconfig.h> 
♦Include <netdir,h> 
llntiXmie <tiUser.h> 



* the form of the comnand line i9i 



main (argc^^argv) 



int 



int fd; 

struct nd_host8ezve ho^tserv; 

Struct ndjaddrlist *addrs; 

struct netconf i^r ^ncfiftf; 

struct tjinitdata *ud; 

void *handXep; 

ektetn int t^ermo; 

if ( at^c 3 ) { 

fprintf (stderr^ "OSAGR: %s liost serviceXn", argvtoi); 
exit(X>; 

iiiiiiiiliiiiiilliiiiiii^ 

hostserv.h_hoat; * argv(l]; 
hostierv,h_d63Wr * argvia}; 

if ((handlep » detnetConfigO ) ^ Mmi.) ( 

no jperror ("setnetconfig failed**); 
exitii); 

* select an a{^f>rQfpriate transport and 

* get address for remote host/seivice 

iiilifiiiiiiiiiiiiiiiiiiiiiiii^ 

^ile ((nconf - getnetconfig<handlep)) I- mx.) { 
if <nconf->nc_S€roantics NCJE^IjCtTS fi£ 

netdirjg^tfcyname (nconf/ thostserv, fiaddrs) — 0) { 



break; 



if (ticonf NOIX) { 



(continued on n^xt page ) 
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Figure 4-6: TLI Datagram Code (continued ) 

lllllllllllllllllllll?^ 

if ((fd * t_ope«i(nconf->ttcjtevi<», Ojms^ HOIX)) < 0) { 

fprlntf (atcferr^ "wwible to <^»n %3\n"/ ncot^'->iwjjc3«vlcse) ; 

illlllliillliiiiiiiiiii^^ 

if (tj>ind(fd, NULL, WJLL\ < 0) { 
tjar3x>r<*tj>ii:id faildd**) 

if ((ud « (struct tjonitdata *]^t^anoc(fd, T_UNITDATA, T_ALL)> 
— NOLL M 

t_error<'*t_all<X! Of tjuttitdata strtictliie failed") ; 
exit (5); 

* yxm first address returned l>y netdirjgetbynameO 

♦ filXdataO will fiXX itt the data to be sent 

llllllllllllllillllllli^^ 

ud->addr - addrs''>n_addrs; 
f illdata <tKh>udata) i 

endnet<:Oaf ig (handlep) t 

/* sedd the datagram 

it (t_sndudata(fd/ ud) <0 > \ 

t_error<'*tj9ndudata failed"); 

exit {€) I 

exit(O); 

\ ) 



For more information about the functions t_open, t__bind, and t__sndudata, 
3ee the manual pages t_open(3N), t_bind(3N), and t_sndudata(3N). 
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Synchronous and Asynchronous Modes 

Transport services are inherently asynchronous, with events occurring indepen- 
dently of the actions of the transport user. For example, a user may be sending 
data over a transport connection when an as)mchronous disconnect indication 
arrives. The user must somehow be informed that the connection has been bro- 
ken. Both the socket interface and TLI provide an asynchronous mode for 
managing such events. As)mchronous mode is most useful for applications that 
expect long delays between events and have other tasks that they can perform 
in the meantime. 

A socket is put into asynchronous mode by calling fcntl () and specifying 
0_NDELAY or 0_NONBLOCK. Qnce in asynchronous mode, all relevant primi- 
tives — send 0 , read () , etc. — return EWOULDBLOCK whenever they 
encounter situations that would have caused them to block if they had been in 
synchronous mode. 

The TLI non-blocking mode is also specified with the 0__NDELAY or 
0_NONBLOCK flag. The 0_NDELAY and 0_NONBLOCK flags can be used when 
the transport provider is initially opened with the t_open { ) function, or later 
with the fcntl () call. If the TLI blocking mode is used, these cause the error 
code EAGAIN to be returned (see the Programmer's Reference ManMfl/, Section 2, 
Introduction). 

There are different levels of as)mchronous operation. Specifying 0_NDELAY or 
0_NONBLOCK puts a socket into non-blocking mode. For true asynchronous 
operation, however, it is also necessary to test for as5mchronous events. Socket- 
based applications normally use select (3N) to test for asynchronous events. 

TLI-based applications should use poll (2) to test for asynchronous events, 
select 0 is supported only for compatibiUty with older applications. 

Both TLI and sockets provide mechanisms for asynchronous event notification. 
Sockets uses fcntl () to request that the system issue a SIGIO signal when it 
becomes possible to perform I/O on a given file descriptor. TLI uses the 
I_SETSIG ioctl. This causes the system to send the process a SIGPOLL sig- 
nal when the I/O event specified actually occurs. The TLI mechanism is the 
more powerful of the two, since it allows users to specify the precise kind of 
I/O event they want to be signaled on (see the streamio(7) manual page for 
the possible kinds of events). 
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A process that issues functions in synchronous mode must still be able to recog- 
nize certain as)mchronous events immediately and act on them if necessary. 
Eight such asynchronous events are specified for TLI and cover both 
connection-oriented and connectionless modes (see the t_look(3N) manual 
page). TLI routines that encounter trouble return the special transport error 
TLCX)K. The user can then use the t_look () function to identify the event that 
generated the error. Alternatively, the transport user can use t_look ( ) to poll 
the transport endpoint periodically for asynchronous events. If a sockets func- 
tion encounters trouble, the primitive will return an errno value directly. 

Error Handling 

TLI attempts to separate communications errors from system errors by defining 
two levels of errors: 

■ Library level errors. Each library function has one or more error returns 
and indicates failure with a -1. An external integer, t_errno, holds the 
specific error number when such an failure occurs. This value is set when 
errors occur but is not cleared by successful library calls. It should there- 
fore be tested only after an error has been indicated. A diagnostic func- 
tion, t_error 0 , is provided for printing out information on the current 
transport error. 

■ System errors. The standard external variable errno, is used to report 
system errors. Such errors can, of course, affect TLI functioning. When 
they do, t_errno is set to TSYSERR and errno is set to indicate the 
specific system error that occurred. The state of the transport provider 
may change if a transport error occurs. 

The socket interface provides a similar facility with getsockopt () when called 
with an option of SO_ERROR. 
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Sockets-to-TLI Conversion 

Table 4-1 shows some approximate TLI/- sockets equivalents. The comment 
field describes the differences. Where there is no comment, either the functions 
are the same or there is no equivalent function in one or the other interface. 



Tabie 4-1: labia of TU/Socicets Equivaients. 



TU function 


Socket function 


Cotntfwnts 


t_open() 


socket ( ) 






socketpair 0 




tJbindO 


bindO 


t_bind ( ) sets the queue depth for passive 
sockets, but bind 0 doesn't. For sockets, the 
queue length is specified in the call to 
listen( ). 


t_optmgmt ( ) 


getsockopt ( ) 
setsockopt 0 


t^optrogntt () manages only transport options, 
getsockopt ( ) and setsockopt ( ) can 
manage options at the transport layer, but also 
at the socket layer and at arbitrary protocol 
layers. 


t_unbind() 


t_close ( ) 


close 0 




t_getinfo() 


getsockopt 0 


t_getinfo 0 returns information about the 
transport, getsockopt () can return informa- 
tion about the transport and the socket. 


t_getstate() 


t^getname ( ) 


getsockname ( ) 




t_sync ( ) 






t_alloc() 


t_free() 


t_look() 




getsockopt with the S0_ERR0R option 
returns the same kind of error information as 
t_look(). 


t_error() 


perror 0 
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Tabie 4-1: Table of TU/Sockets Equivalents, (oontinued) 



TU function 


Socket function 


Comments 


t_connect ( ) 


connect () 


A connect () can be done without first bind- 
ing the local endpoint. The endpoint must be 
bound before calling t_connect ( ) . A con- 
nect ( ) can be done on a connectionless end- 
point to set the default destination address for 
datagrams. 


t_rcvconnect ( ) 


t_listen() 


listen 0 


t_listen() waits for connection indications, 
listen ( ) merely sets the queue depth. 


t_accept ( ) 


accept 




t_snd() 


send ( ) 
sendto ( ) 
sendmsg 0 


sendto 0 and sendmsg () operate in connec- 
tion mode as well as datagram mode. 


t__rcv() 


recv ( ) 
recvfromO 
recvmsg ( ) 


recvfromO and recvmsg () operate in con- 
nection mode as well as datagram mode. 


t_snddis ( ) - 


t_rcvdis ( ) - 


t_sndrel() 


shutdown ( ) 




t_rcvrel() - 


t_sndudata() 


sendto ( ) 
sendmsg ( ) 




t_rcvudata ( ) 


recvfromO 
recvmsg ( ) 




t_rcvuderr() 


readO 


read ( ) 


In TLI, you must push the tirdwr module 


write ( ) 


write ( ) 


before calling read ( ) or write () ; in sockets, 
it is sufficient just to call read ( ) or write ( ) . 
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Moving Sockets Applications to System V Release 4 

Although System V Release 4 sockets and the BSD sockets implementation are 
largely compatible, there are some differences an application programmer must 
be aware of before moving a BSD sockets-based application to System V 
Release 4. These differences are described in Table 4-2. 



Table 4-2: Differences in Soclcets Impiementations 



BSD 


UNIX System V Release 4«0 


Connection-Mode Primitives 


connectO 


If connectO is called on an unbound 
socket, the protocol determines 
whether or not the endpoint will be 
bound before the connection takes 
place. 


When connectO, is called on an 
unbound socket, that socket is always 
bound to an address selected by the 
transport provider. 


Data Transfer Primitives 


writeO 


writeO will fail with errno set to 
ENOTCONN if it is used on an uncon- 
nected socket. 


A call to writeO will appear to 
succeed, but the data will be discarded. 
The socket error option SO_ERROR will 
be set to ENOTCONN if this occurs. 


writeO can be used on type 
SOCK_DGRAM sockets (either AF_UNIX 
or AF_INET domains) to send zero 
length data. 


A call to write () will return -1, with 
errno set to ERANGE. The functions 
send ( ) , sendto ( ) , or sendmsg ( ) 
should be used to send zero length 
data. 
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Table 4-2: Differences In Sockets Implementations (continued) 



BSD 


UNIX System V Release 4.0 


readO 


A call to readO will fail with errno 
set to ENOTCONN if read () is used on 
an unconnected socket which needs to 
be connected. 


A call to readO will return zero bytes 
read if the socket is in blocking mode. 
If the socket is in non-blocking mode, it 
will return a -1 with errno set to 
EAGAIN. 


sendmsgO and readmsgO 


If the MSG_PEEK flag has been set 
when sendmsg 0 is called, and access 
rights are available, the access rights 
will be copied, leaving them available 
for reading by a subsequent call to 
recvmsgO . 


If the MSG_PEEK flag is specified in a 
call to recvmsg () , and access rights 
are available, the access rights will be 
transferred to the user buffer associated 
with the receiving socket. They are 
then destroyed, and the transferring 
socket has no further access to them. 
They are therefore unavailable to a 
subsequent call to recvmsg ( ) . Any 
data associated with the access rights 
will also be copied to the user buffer 
and will not be available to 
recvmsgO • 


Information Primitives 


getsocknameO 


getsocknameO will work when a pre- 
viously existing connection has been 
closed. 


get:sockname() will return -1 and 
errno will be set to EPIPE if a previ- 
ously existing connection has been 
closed. 
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Table 4-2: Differences In Sockets Implementations (continued ) 



BSD 



UNIX System V Release 4.0 



ioctlO and fcntlO 



SIOCSPGRP/FIOSETOWN/F SETOWNO 



The 

SIOCSPGRP/FIOSETOWN/F_SETOWN 
ioctl 0 's and the F_SETOWN 
f cntl () take as argument a positive 
process id or negative process group 
indentifying the intended recipient list 
of subsequent SIGURG and SIGIO sig- 
nals. 



This is not the case in SVR4. The only 
acceptable arguments to these system 
calls is the caller's process id or a nega- 
tive process group which has the same 
absolute value as the caller's process id. 
In other words, the only recipient of 
SIGURG and SIGIO signals is the cal- 
ling process. 



Local Management 



bindO 



bind ( ) uses the credentials of the user 
at the time of the bind ( ) call to deter- 
mine whether the port requested 
should be allocated or not. 



A call to socket ( ) causes the user's 
credentials to be remembered and used 
to validate addresses used in bind ( ) . 



setsockopt 0 



setsockopt () can be used at any 
time during the life of a socket. 



Because of the state diagram specified 
by the Transport Provider Interface 
(TPI), a setsockopt () operation on a 
transport provider conforming to this 
specification will fail if issued on a 
socket that is not bound to a local 
address. 



4-20 



Programmer's Guide: Networking Interfaces 



Sockets Migration and Sockots-to-TLI Conversion 



Tabie 4-2: Differences in Sockets Impiementations (continued ) 



BSD 


UNIX System V Release 4.0 




Specifically, if a socket is unbound and 




setsockoptO is used, then the 




operation will succeed in the AF_INET 




domain, but will fail in the AF_UNIX 


Shutdown 0 



If shutdown is called with the value of 
how equal to zero, further attempts to 
receive data will return zero bytes 
(EOF). 



If shutdown 0 is called with the value 
of how equal to 2, further atempts to 
receive data will return EOF. Attempts 
to send data will return -1 with errno 
set to EPIPE with a SIGPIPE issued. 

If shutdown 0 is called with a value 
of two for how, further attempts to 
receive data will return EOF, and 
attempts to send data will return -1 
with errno set to EPIPE with a SIG- 
PIPE issued. 



Calling shutdown with the value of 
how equal to zero will not cause further 
attempts to receive data to return zero 
bytes if the read(2) system call is used 
and the socket is in nonblocking mode. 
In this case read will retum -1 with 
errno set to EAGAIN. If one of the 
socket receive primitives is used, the 
correct result (EOF) will be returned. 

The same results will occur, except that 
attempts to send data using the write 
system call will cause errno to be set 
to EIO. As in the above case, if a 
socket primitive is used, the correct 
errno will be returned. 

The same results will occur, except that 
attempts to send data using the 
write () system call will cause errno 
to be set to EIO. If a socket primitive 
is used, the correct errno will be 
returned. 
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Table 4-2: Differences in Socicets Impiementations (continued ) 



BSD 


UNIX System V Release 4.0 


Signals 


SI6I0 


SIGIO is delivered every time new 
data are appended to the socket input 
queue. 


SIGIO is delivered only when data are 
appended to a socket queue that was 
previously empty. 


SIGURG 


A SIGURG is delivered every time new 
data is anticipated or actually arrives. 


A SUGURG is delivered only when there 
is no urgent data already pending. 


S_ISSOCK 


The ISSOCK macro takes the mode of 
a file as an argument. It returns 1 if 
the file represents a socket and 0 other- 
wise. 


The ISSOCK macro does not exist. In 
SVR4, a socket is defined as a file 
descriptor associated with a streams 
character device that has the socket 
module pushed onto it. 


S_IFSOCK() 


This file type identifies a socket 
descriptor. 


There is no socket file type, and this 
♦define does not exist. 


Miscellaneous 


If an invalid buffer is specified in a 
function, the function will normally 
return -1 with errno set to EFAULT. 

If Is -1 is executed on a directory 
that contains a UNIX domain socket, an 
s will be printed on the left side of the 
mode field. 


If an invalid buffer is specified in a 
function, the user's program will prob- 
ably coredump. 

If Is -1 is executed on a directory 
that contains a UNIX domain socket, a 
p will be printed on the left side of the 
mode field. 
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Table 4-2: Differences in Soclcets impiementations (continued ) 



BSD 


UNIX System V Release 4.0 


Executing Is -F will cause an equals 
sign (=) to be printed after any 
filename that represents a UNIX 
domain socket. 


Nothing will be printed after a 
filename that represents a UNIX 
domain socket. 
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Introduction to RPC 



The Remote Procedure Calls (RPC) mechanism is a high-level communications 
paradigm for network applications. By use of RPC, programs on networked 
platforms can communicate with remote (and local) resources. 

Organization of Technical Information 

This chapter, 'Introduction to Remote Procedure Calls", provides an overview 
of the RPC mechanism and the programming tools and protocols that supp)ort 
RPC. Terms used throughout this section are defined. 

The "rpcgen Progranuning Guide" chapter provides instruction on the use of 
rpcgen, the compiler used for creating C-language programs that use RPC. The 
RPC programming language is described in this chapter. 

The "Remote Procedure Call Programming Guide" chapter describes in detail 
the C-language interface to the RPC environment. The RPC interface allows 
programmers access to RPC at various levels, frpm high to low. High level RPC 
provides transparency and portability. Lower levels offer greater control of the 
communications. This chapter includes guidance on selecting an appropriate 
level for a given application. 

External Data Representation (XDR) is the protocol used by RPC for platform- 
independent data communications. The "External Data Representation Stan- 
dard: Protocol Specification" chapter is an XDR reference for RPC program- 
mers. 

The "Remote Procedure Calls; Protocol Specification" chapter is a complete 
RPC programming reference. 

Definitions 

Bottom Level Lowest of the four lower RPC levels; programs 

written to this level can control many transport- 
specific d(etails. 

connection-oriented transport Connection-oriented transports are reliable and 

support byte-strearh deliveries of unlimited data 
size. 
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connectionless transport 

datagram transport 
deserializing 

Expert Level 

Intermediate Level 

network client 

network service 
ping 

remote program 
RPC language 
RPC Package 

RPC Protocol 



Connectionless transports have less overhead 
than connection-orient transports but are less 
reliable and maximum data transmissions are 
limited by buffer sizes. 

See connectionless transport. 

Converting data from XDR format to a 
machine-specific representation. 

Second-lowest of the four lower RPC levels; pro- 
grams written to this level can: control client 
and server characteristics; interface with 
rpcbind; manipulate service dispatch. 

Second-highest of the four lower RPC levels; 
programs written to this level specify the tran- 
sport they require. 

A process that makes remote procedure calls to 
services. 

A collection of one or more remote programs. 

A call to procedure 0 of an RPC program. Ping- 
ing is used to verify the existence and accessibil- 
ity of a remote program. Pinging can also be 
used to time network communications. 

Software that implements one or more remote 
procedures. 

A C-like programming language recognized by 
the rpcgen compiler. 

The collection of software and documentation 
used to implement and support remote pro- 
cedure calls in System V. TTie RPC Package 
implements and is a superset of the functionality 
of the RPC Protocol 

The message-passing protocol that is the basis of 
the RPC package. 
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RPC/XDR 
serializing 

server 

Simplified Interface 
transport 

Top Level 

universal address 

virtual circuit transport 
XDR language 



See RPC language. 

Converting data from a machine-specific 
representation to XDR format. 

Software that implements network services. 

The simplest level of the RPC package. 

Refers to the fourth layer of the Reference 
Model of Open Systems Interconnection (OSI). 

Highest of the four lower RPC levels; programs 
written to this level specify the type of transport 
they require. 

A machine-independent representation of a net- 
work address. 

See connection-oriented transport. 

A protocol specification language for data 
representation. RPC language builds on and is a 
superset of XDR. 
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RFC allows network applications to use specialized kinds of procedure calls 
designed to hide the details of underlying networking mechanisms. RPC is 
transport independent, able to take advantage of whatever kinds of networking 
mechanisms (such as TCP/IP or ISO) may be available. RPC implements a logi- 
cal client- to- server communications system designed specifically for the sup- 
port of network applications. Generic facilities, such as rpcbind, associate net- 
work services with universal network addresses. 

Refer to Figure 5-1. With RPC, the client makes a procedure call that sends data 
packets to the server, as necessary. When these packets arrive, the server calls a 
dispatch routine, performs whatever service is requested, sends back the reply, 
and the procedure call returns to the client. 
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Figure 5-1: Network Communication with tlie Remote Procedure Cali 
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Programming v^ith RPC produces programs that are designed to run within a 
client/server network model. Such programs use RPC mechanisms to avoid the 
details of interfacing to the network, and provide network services to their call- 
ers without requiring that the caller be aware of the existence and function of 
the underlying network. For example, a program can simply call rusersO, a C 
routine that returns the number of users on a remote machine. The caller is not 
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RPC Overview 



explicitly aware of using RPC — the call to rusersO is as simple as a call to 
malice () . 

This section addresses only the C interface to RPC, but ren\ote procedure calls 
can be made from any language. Note too that although this section describes 
the use of RPC for communication between processes on different machines, 
RPC works just as well for communication between different processes on the 
same machine. 

The following paragraphs provide capsule overviews of the key components 
and leading characteristics of RPC. Descriptions will address: 

■ "RPC Versions and Numbers" — RPC uses a program number, program 
version, procedure number tuple to uniquely identify procedures that can 
be called via RPC. 

■ "Network Selection" — Programs can be written to operate over specific 
transports and transport types, or can be written to operate over system- 
or user-chosen transports. 

■ "The rpcbind Facility" — rpcbind is a facility used to associate network 
services with universal network addresses. 

■ 'The Lower RPC Levels" — The lower RPC levels available to client and 
server programs allow for greater control of RPC communications. 

■ "External Data Representation (XDR)" — Data transmitted between RPC 
clients and servers is encoded in XDR transfer syntax. 



RPC Versions and Numbers 

Each RPC procedure is uniquely identified by a program number, version 
number, and procedure number. 

The program number identifies a group of related remote procedures, each of 
which has a different procedure number. Each program also has a version 
number, so when a minor change is made to a remote service (adding a new 
procedure, for example), a new program number does not have to be assigned. 
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To call a procedure to find the number of remote users, for example, you would 
look up the appropriate program, version and procedure number in a reference 
manual (just as you would look up the name of a memory allocator if you 
wanted to allocate memory). 

RPC programs should be assigned program numbers according to rules detailed 
in the "Program Number Assignment" sub-section of the "Remote Procedure 
Calls: Protocol Specification" chapter in this guide. 



Network Selection 

Network selection is a simple way by which users and applications may d5mam- 
ically select transports, according to both their preferences and the available 
transports. It is based on two mechanisms, the /etc/netconf ig database, 
which lists the transports available on the host and identifies them by type, and 
the optional environmental variable NETPATH, which allows the user to specify 
preferences among the transports available in /etc/netconf ig that are accept- 
able to the application. 



NOTE 



To create a service for a particular transport, an application must interface to 
RPC at a level below the top level, i.e., the level composed of 
clntjcreateO and its associated routines. Only then can it specify the 
types of transports that it prefers. See below for details about the various 
RPC levels. 

The /etc/netconf ig file contains several lines, each of which corresponds to 
an available transport. Here are some possible entries: 
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# The Hdti»r]c Configuration Fil^. 

# Each 0atxy is Of the form: 

I network^id semamtics flags protofareily protoname device nametoaddr^libs 

iiiiiiiiiB 

ticlt* tpi_cJ.tA V lookback - /dev/ticlti /usr/iib/dtraddr.so 
ticots tpi^cots V loo|3baqk /<3ev/tioot9^ /u9r/lib/3tradc|r<so 
ticotdotd tpijcotj9j>rd v Xocpbaelc - /dew/ticotaotd /usr/llb/3traddr,do 
dtarlan tpijcots it osinet /dav/starlan /udr/lib/dtraddr.^ 
stariang tpij5Xt« v oainet /ctev/starXang /usr/iib/stwiaefc^flo 
tcp tpijaotsjotd V inefc tcp /dev/t<^ /udr/lib/tcpip.a«> 
TJ<^? tpij?lt» V Inet /dev/uc^ /uprAib/t<^ip,|ip 
Icnip tpijcaw inet ioflp /dey/ionp /war/iib/tqplp^BO 
sawi^ t|>i_t«tf - ini^ - /d^/£awip /u^/Hb/tq^p^.ao 



For the details about /etc/netconf ig, and about the applications interface to 
it, see the getnetconf ig(3N) manual page and the "Network Services" 
Chapter in the System Administrator's Guide. Here, we just want to mention a 
few points: 

■ Each entry contains an identifier (the first field) which gives the network 
identifier by which the transport is commonly known. 

■ Each entry also contains a flag or set of flags (the third field) that 
identifies it by type — the v flag, for example, identifies any transport 
that is 'visible/ 

■ The last field names a run-time linkable module that contains the name- 
to-address translation routines associated with the transport. (See below). 

■ The loopback transports are required for registering services with 
rpcbind. They are local transports, available only to local clients and 
servers, and hence are more secure than other transports. 



The format of NETPATH is simple: an ordered list of network identifiers 
separated by colons (:) (for example: udp : tcp : starlan). By setting NETPATH, 
the user can specify the order in which the application should try the various 
networks. If NETPATH is not set, the system defaults to all visible transports 
specified in /etc/netconf ig, in the order they appear. 
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NOTE 







Applications can clioose to ignore a user's netpath. 



RPC divides selectable transports into the following types: 

netpath Choose from those transports that have been specified in the 

NETPATH environment variable. If NETPATH is not set, the sys- 
tem defaults to all visible transports specified in 
/etc/netconf ig, in the order they appear. 

" " (null) — same as selecting netpath. 



visible 

circuit__v 

datagrani_v 
circuit_n 

datagram_n 

udp 

tcp 



Choose those transports that have the visible flag (VO set in 
their /etc/netconf ig entries. 

Same as visible, but restricted to connection-oriented tran- 
sports. 

Same as visible, but restricted to connectionless transports. 

Choose from whatever is defined in NETPATH, but restrict to 
connection-oriented transports. 

Choose from whatever is defined in NETPATH, but restrict to 
connectionless transports. 

(Obsolete. For backwards compatibility.) — specifies Internet 
User Datagram Protocol (UDP). 



(Obsolete. For backwards compatibility.) 
Transmission Control Protocol (TCP). 



specifies Internet 



When a transport-dependent application begins execution, it begins by calling 
the setnetconf ig(), getnetconf ig() and endnetconf igO routines, using 
them to search /etc/netconf ig for a transport of appropriate type. This 
information is then stored in local data structures of type struct netconf ig 
and is available for later use. setnetconf igO, getnetconf ig(), and end- 
netconf ig() are described on the getnetconf ig(3N) manual page; the Net- 
work Selection Administrative file /etc/netconf ig is described on the 
netconf ig(4) manual page. 



Introduction to Remote Procedure Calls 



5-9 



RPC Overview 



Taken together, these mechanisms allow a fine degree of control over network 
selection: a user can specify a preferred transport, and if it is reasonable, appli- 
cations will use it. In cases where the specificil transport is inappropriate (as, 
for example, when a remote server does not support a specified transport) the 
application should automatically try others with the right characteristics. 

Name-to-Address Translation 

Each transport has an associated set of routines that convert between universal 
network addresses (string representations of transport addresses) and their local 
address representation. These universal addresses are passed around within the 
RPC system (for example, between rpcbind and a client). When any program- 
ming interface to the transport layer is made, a transport-specific name-to- 
address translation routine is called to convert the universal address into local 
form. Each transport has associated with it a run-time loadable library that con- 
tains the name-to-address translation routines associated with it. The main 

Translates from host/ service pairs and a 
netconf ig structure (e.g. serverl, rpcbind) 
to a set of netbuf addresses, netbuf 's are 
Transport Layer Interface (TLI) structures that 
are used at run-time to contain transport-specific 
addresses. 

Translates from netbuf addresses and a 
netconf ig structure into host/ service pairs. 

Translates from universal addresses and a 
netconf ig structure to netbuf addresses. 

Translates from netbuf addresses and a 
netconf ig structure to universal addresses. 

For more details on these routines, see the netdirON) manual page. 



translation routines are: 
ne t di r_ge t byname : 

netdir_getbyaddr: 

uaddr2taddr: 

taddr2uaddr: 
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The rpcbind Facility 

Client programs need a way to find server programs; that is, they need a way to 
look up the addresses of server programs. Network transport services do not 
themselves provide such a service; they merely provide process-to-process mes- 
sage transfer across a network. A message is sent to a transport-specific net- 
work address. A network address is a logical communications channel; by wait- 
ing on a network address, a process receives messages from the network. 

RPC, being transport independent, makes no assumptions about the structure of 
a network address. It deals with universal addresses, specified only as null- 
terminated strings of characters. RPC translates universal addresses into local 
transport addresses by using routines specific to each transport provider. For 
more details on these routines, see the netdir(3N) manual page. 

Operating systems provide (differing) mechanisms by which a process can wait 
on a network address, i.e, synchronize its activity with arriving messages. Thus, 
messages are not sent across networks to receiving processes, but rather to the 
transport address at which receiving processes pick them up. Transport 
addresses are valuable because they allow message receivers to be specified in a 
way that is independent of the conventions of the receiving operating system. 
The rpcbind protocol defines a network service that provides a standard way 
for clients to look up the transport address of any remote program supported 
by a server. Because the rpcbind protocol can be implemented for any tran- 
sport, it provides a single solution to a general problem that works for all 
clients, all servers and all networks. 

Address Registration 

Because rpcbind is responsible for mapping network services to their 
addresses, its address must be well known. The name-to-address translation 
routines for any particular transport should know and reserve a particular 
address for rpcbind. 

In the Internet domain, this problem is solved by always assigning rpcbind the 
port number 111. Unfortunately, this simple solution is not acceptable on all 
transports. 

rpcbind begins each session by registering its location on each of the tran- 
sports supported by the host, rpcbind is the only network service that must 
have such a well-known address. The address must be well-known for a given 
transport because rpcbind is responsible for registering the addresses of other 
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network services and making those addresses available to network clients. 
Thus, services make their addresses available to clients by registering their 
addresses with their host's rpcbind daemon. Thereafter, the addresses of the 
services are available to rpcinf o(lM) and to programs using library routines 
specified in rpcbind(3N). 

RPC-based servers typically get mapped to network addresses at run time, and 
then they register with rpcbind, and neither they nor their clients can make 
any assumptions about what those network addresses will be. 

rpcbind is started by the system or RPC administrator. Both server programs 
and client programs call rpcbind. 



NOTE 



Although client and server programs and client and server machines are 
usually distinct, they need not be. A server program can also be a client 
program, as when an NFS server calls an rpcbind server. Likewise, when 
a client program directs a "remote" procedure call to its own machine, the 
' machine acts as both client and server. 

As part of its initialization, a server program calls its hosf s rpcbind daemon to 
register itself in the host's registered-address map. Whereas server programs 
call rpcbind to update address maps, clients call them to query those maps. 
To find a remote program's address, a client sends an RPC call message to a 
server machine's rpcbind daemon; if the remote program is on the server, the 
daemon returns the relevant address in an RPC reply message. The client pro- 
gram can then send RPC call messages to that address. 

The rpcbind protocol (for details, see the "Remote Procedure Calls: Protocol 
Specification" chapter) provides a procedure, RPCBPROC_CALLIT(), with which 
rpcbind can assist a client in making a remote procedure call. A client pro- 
gram passes the target procedure's program number, version number, pro- 
cedure number (for a discussion of these numbers, see the "Remote Procedure 
Call Programming Guide" chapter) and arguments in an RPC call message, 
rpcbind then looks up the target procedure's address in the address map and 
sends an RPC call message, including the arguments received from the client, to 
the target procedure. 

When the target procedure returns results, RPCBPROC_CALLIT() passes them on 
to the client program. It also returns the target procedure's address so the client 
can later call it directly. 
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The RPC library provides an interface to all rpcbind procedures. Some of the 
RPC library procedures also call rpcbind automatically for client and server 
programs. 

The rpcinfo Command 

rpcinf o is a shell command that reports current RPC registration information 
known to rpcbind (and can be used, by administrators, to delete registrations), 
rpcinfo can be used to find all the RPC services registered on a specified host 
and to report their universal addresses and the transports for wrhich they are 
registered. It can also be used to call (ping) a specific version of a specific pro- 
gram on a specific host using a TCP or UDP transport, and to report whether a 
response is received. For details, see rpcinfo (IM). 

The Lower RPC Levels 

There are various levels at which it is possible to interface to the RPC library 
services. These levels are described in detail in the "Remote Procedure Call 
Programming Guide" chapter. Understanding the lower levels of RPC is help- 
ful but not necessaiy if you plan to use rpcgen to generate your RPC applica- 
tions. For usage of rpcgen, refer to the "rpcgen Programming Guide" 
chapter. 

Figure 5-2 illustrates client-side lower level interfaces, that are available for 
transport-handle creation. Figure 5-3 illustrates transport-handle creation for an 
RPC server. Note the similarity of hierarchies on each side. 
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Figure 5-2: Client-Side RPC Lower Levels 

clnt_create (hostr prog, vers, nettype) 
'Top Lever - transport is selected by network type. 



(Network Selection) 
Application controb transport selection below this point. 

I 
I 

clnt_tp_create (host, prog, vers, netconfig) 
"Intermediate Level" - application knows what transport it will use. 

I 
I 

(Name-to-Address Translation) 
I 
I 

clnt_tli_create (fd, netconfig, . . . ) 
"Expert Level" - Application can now directly manipulate the transport. 

I 
I 



I I 
I I 
clnt_dg__create ( ) clnt_vc_create ( ) 

"Bottom Level" - Only very specialized applications need access to this level. 



5-14 



Programmer's Guide: Networking interfaces 



RPC Overview 



Figure 5-3: Server-Side RPC Lower Leveis 

svc_create (dispatch, prog, vers, nettype) 
'Top Lever - transport is selected by network type. 



(Network Selection) 
Application controls transport selection below this point. 



svc__tp__create (dispatch, prog, vers, netconfig) 
'Intermediate LeveV - application knows what transport it will use. 

I 

I 

(Name-to-Address Translation) 



svc_tli_create (fd, netconfig, . . . ) 
"Expert Lever - Application can now directly manipulate the transport. 



I I 
I I 
svc__dg_create ( ) svc__vc_create ( ) 

''Bottom Level" - Only very specialized applications need access to this level. 



External Data Representation 

RPC uses External Data Representation (XDR), a protocol for the machine- 
independent description and encoding of data. XDR is useful for transferring 
data between different computer architectures. 

RPC can handle arbitrary data structures, regardless of different machines' byte 
orders or structure layout conventions, by always converting them to XDR 
representation sending them over the wire. The process of converting from a 
particular machine representation to XDR format is called serializing, and the 
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reverse process is called deserializing. For a detailed discussion of XDR, see the 
"External Data Representation Standard: Protocol Specification" chapter. 
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An Overview of rpcgen 

rpcgen is a compiler. It accepts a remote program interface definition written 
in a language, called RFC Language. RFC Language is similar to C. rpcgen 
produces a C language output for RFC programs. This output includes: 

■ stub versions of the client routines 

■ a server skeleton 

■ XDR filter routines for both parameters and results 

■ a header file that contains common definitions 

■ (optionally) dispatch tables that the server can use to check authorizations 
and then invoke service routines. 

rpcgen's output files can be compiled and linked in the usual way. 

The client stubs interface with the RFC library and effectively hide the transport 
from their callers. The server skeleton similarly hides the transport from the 
server procedures that are to be invoked by remote clients. 

The developer writes server procedures (in any language that observes system 
calling conventions) and links them with the server skeleton produced by 
rpcgen to get an executable server program. To use a remote program, the pro- 
grammer writes an ordinary main program that makes local procedure calls to 
the client stubs produced by rpcgen. Linking this program with stubs pro- 
duced by rpcgen creates an executable program. (At present the main program 
must be written in C.) 

rpcgen options can be used to suppress stub generation and to specify the tran- 
sport to be used by the server skeleton. 

rpcgen reduces the development time that would otherwise be spent coding 
and debugging low-level routines, at a small cost in efficiency and flexibility. 
For speed-critical applications, though, rpcgen allows programmers to mix 
low-level code with high-level code. Hand-written routines can be linked with 
the rpcgen output without any difficulty. Also, one may proceed by using 
rpcgen output as a starting point, and then rewriting it as necessary. (For a 
discussion of RFC programming without rpcgen, see the "Remote Procedure 
Call Frogramming Guide" chapter.) 
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Organization of Technicai information 

This chapter provides rpcgen tutorial and user infonnation. 

The section titled "An rpcgen Tutorial" describes through examples how a pro- 
grammer can use rpcgen to do such things as: 

■ convert an application to run over a network 

■ use rpcgen to create XDR routines 

■ make use of rpcgen-supported preprocessing directives. 

The "Common RFC Programming Techniques" section suggests some coding 
and rpcgen usage techniques. 

Finally, the "RFC Language Reference" provides a complete description of the 
RFC programming language recognized by the rpcgen compiler. 
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The details of programming applications to use Remote Procedure Calls can be 
overwhelming. Perhaps most daunting is the writing of the XDR routines 
necessary to convert procedure arguments and results into their XDR format 
and vice-versa. 

Fortunately, rpcgen(l) exists to help programmers write RPC applications sim- 
ply and directly, rpcgen does most of the dirty work, allowing programmers 
to debug the main features of their application, instead of requiring them to 
spend most of their time on their transport interface code. 

This section presents some basic rpcgen programming examples. 

Converting Local Procedures into Remote Procedures 

Assume an application that runs on a single machine. Suppose we want to con- 
vert it to run over the network. Here we will show such a conversion by way 
of a simple example program that prints a message to the console. The source 
file for the original program might look like: 
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/* pritktmsg.e: print it mdssagd on the console */ 
flncluciB <st<51o.h> 

int aityc; 
<!har *«?gvn; 

lillliiiliiiliiiiiiiiii^ 



char ^saage; 
if (a»g<? i- 2) I 

f printf (9tderr^ "asage: %3 <<lne»»ag©>\n", axigv[01); 

lliilillilllllllill 

fpaKtotf («tderr« '•%a2 eouXdn't priwt jTOnar »efljj^(&\n^/ 

prlntf ( "Measage DoliverBd r \n" ) ; 
/* Print a message to the ccnsoXe, */ 

/* Betum a boolean indicating wtieWjer the message ms actually printed. */ 

printinessage (msg) 

<:^har *>nsg; 

lllllllllllllllllllll^ 

f ** £opeii('»/dev/coin9ple*'« "w"); 

if (f — mm { 

return (0); 

fprintf(f, ns\n*, itisg); 

fclose(f); 

return (1); 



For local use on a single machine, this program could be compiled and executed 
as follows: 
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$ cc printrodg.c prlntnug 

V : J 

If the printmessage () function were turned into a remote procedure, it could 
be called from anywhere in the network. It is not difficult to make a procedure 
remote. 



wm 



In the context of RPC programnfiing, it has become acceptable to use the 
term procedure to refer to a C-language function. The terms are used inter- 
changeably in this guide. 



In general, it is necessary to figure out what the tj^^es are for all procedure 
inputs and outputs. Here, the procedure printmessage {) takes a string as 
input, and returns an integer as output. Knowing this, we can write a protocol 
specification in RPC language that describes the remote version of printmes- 
sage () . The RPC language source code for such a specification might look 
like: 



/* m5g,x; Reanote message printing protocol */ 

program MESSACEPftDG { 

version MESSAGEVERS { 



Int PRINTMESSAGE (string) « 1; 



) • 0x20000001; 



Remote procedures are always declared as being part of remote programs. The 
above is actually a declaration for an entire remote program, one that contains 
the single procedure PRINTMESSAGE. 



rpcgen Programming Guide 



6-5 



An rpcgen Tutorial 



NOTE 



In the context of RPC programming, the term "remoteprogram" actually 
refers to a collection of (related) procedures. 



In this example, the PRINTMESSAGE procedure is declared to be procedure 1, in 
version 1 of the remote program whose number is 0x20000001. [Refer to 
"Program Number Assignment" in the "Remote Procedure Calls: Protocol 
Specification" chapter for guidance on choice of program numbers J 

By convention, all RPC services provide for a procedure 0 ; a call to a remote 
program's procedure 0 should do nothing (a "no-op") except succeed. To ping 
means to call procedure 0 of a remote program. Pinging is used to verify the 
existence and accessibility of a remote program. 

Using rpcgen, no null procedure (procedure 0) need be written because 
rpcgen generates it automatically. 

Notice that the program and procedure names are declared with all capital 
letters. This is not required, but is a good convention to follow. 

Notice also that the argument type is string and not char * as it would be 
in C. This is because a char * in C is ambiguous. Programmers usually 
intend it to mean a null-terminated string of characters, but it could also 
represent a pointer to a single character or a pointer to an array of characters. 
In RPC language, a null-terminated string is unambiguously called a string. 

There are just two more things to write: 

■ the remote procedure itself 

■ the main client program that calls it 

Here's one possible definition of a remote procedure to implement the 
PRINTMESSAGE procedure we declared above: 
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^ ma^jptoC.Ct irv^IdkndatatlOkl Of the tBmote procedute "^pzlnUnasd^ig^^ 



♦Include <5tdio,h> 
♦include <ij)c/tpc.h> 
♦Include '*insg*ii*' 



/♦ itlways needed ♦/ 

/* in9g»h will be generated by xpcgen */ 



* Remote version of "printmeddage** 
int * 

printittessagejl <msg) 
char **ni9g; 

lllllllllllllllllllll^^ 

stiitic int result; /* wlist be static! */ 
FILE *f ; 

f - fopenC/dev/console"/ **w*^); 

if (f — ma*) { 

result •« D; 
return <&result>; 

fprintf^f, "%s\n'', *msg>; 
fclose(f); 
result * 1; 
return (iresult); 



Notice that the declaration of the remote procedure printmessage_l () differs 
from that of the local procedure printmessage {) in three ways: 

■ It takes a pointer to a string instead of a string itself. This is true of all 
remote procedures: they always take pointers to their arguments rather 
than the arguments themselves. 

■ It returns a pointer to an integer instead of an integer itself. This is also 
characteristic of remote procedures: they return pointers to their results. 
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When rpcgen is used, it is essential to have result (in this 
example) declared as static. 



In the code generated by rpcgen, the result address is converted to XDR 
format after the remote procedure returns. If the result were declared 
local to the remote procedure, references to its address would be invalid 
after the remote procedure returned. So the result must be declared 
static when rpcgen is used. 

■ It has _1 appended to its name. In general, all remote procedures called 
by rpcgen are named by the following rule: the procedure name in the 
program definition (here PRINTMESSAGE) is converted to all lower-case 
letters, an underbar (_) is appended to it, and the version number (here 1) 
is appended. 



The last thing to do is declare the main client program that will call the remote 
procedure. Here is one possibility: 



#incXtjcte "^tpc/xpc.h^ 
♦Include '^S^.h'* 

jnalnCacgq, az^^ 



Int ^result; 
char *aearwer; 
<:har ^dB^^; 

it (aacgc 3) { 

f prlntf (stderr, 

''usage; %3 ho3t message\n«y argv{0]); 
exit(l>; 



(continued on next page ) 
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* ^if^ v^liMd ot nmtmd line mxi^ruMuitd 

^iiiiiiiiiiiiiiiiiiiiiii 

/* 

* Create client ♦*handXe*' used for calling MESSaGEPROG on the 

* setver desicfnated On the ccmnand line. 
*/ 

cX w clntjsteate (server, MESS»<»)ftOG, MBSSJWSEVEIRS^ 

''visible") ; 
if (ci — NDU»> { 

iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii 

* Couldn't establish connection with server » 

* Print error »essage and die. 

clnt jxjreateerror ( server) ; 
exitd); 



} 



* Call the remote prpqedare "printmessage" on the server 

result « printinessa^e_l<&inessa!^, Cl)^ 
if (result — NOLL) f 

^ An error occurred while calling the server. 

* Print error message and die, 

clnt_perror(cl,^ server); 
exitd); 

iiiiiiiiiiiiiiiiiilii:^^ 

* Olcay, we successfully called the remote procedure, 
if (*result «-» 0) { 

^ ^Server was unable to print our message. 

* Print error message and die* 

fprintf <stderr, <*%s: %S couldn't print your messageXn", 
argv{0], server); 
exit(l); 



(continued on next page ) 
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iiiiiiiiiiiiiiiiiiiiiiiiiiiiii^^ 

* ^ tn^ssdge got pitlnted on the ae£Vei^ d CdifxdOld 









ex 
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There are four things to note here: 

■ First a client handle is created using the RFC library routine 
clnt_create () . This client handle will be passed to the stub routines 
that call the remote procedure. (The client handle can be created in other 
ways as well, see the "Remote Procedure Call Programming Guide" 
chapter for details.) 

■ The last parameter to clnt_create () is ^ ^visible' which specifies 
that any transport noted as visible in /etc/netconf ig can be used. 

■ The remote procedure printmessage_l {) is called exactly the same 
way as it is declared in msg jroc . c except for the inserted client handle 
as the second argument. It also returns a pointer to the result instead of 
the result itself. 

■ The remote procedure call can fail in two ways. The RPC mechanism 
itself can fail or, alternatively, there can be an error in the execution of the 
remote procedure. In the former case, the remote procedure [in this case 
Printline ssage_l () ] returns with a NULL. In the later case, however, 
the details of error reporting are application dependent. Here, the error is 
being reported via *result. 



Here's how to put all the pieces together: 



$ rpcgen nwg.x 

$ cc xprttttiwg.c nagjdnt.c tp«lnt»sg -OnBl 
$ cc iBsg_j>roc.c in8g__avc.q -o iiisg[_a0rver -Inal 
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Two programs are compiled here: the client program rprintmsg and the 
server program msg_server. Before doing this, rpcgen was used to fill in the 
missing pieces. 

Here is what rpcgen (called without any flags) did with the input file msg.x: 

1. It created a header file called msg, h that contained #def ine statements 
for MESSAGEPROG, MESSAGEVERS and PRINTMESSAGE for use in the 
other modules. 

2. It created the client "stub" routines in the msg_clnt . c file. Here there 
is only one, the printmessage_l () routine, that was called from the 
rprintmsg client program. If the name of an rpcgen input file is 
FOO.x, the client stubs output file is called FOO_clnt . c. 

3. It created the server program in msg^svc . c that calls printmes- 
sage_l ( ) from msg^roc . c. The rule for naming the server output file 
is similar to the previous one: for an input file called FOO . x, the output 
server file is named FOO svc . c. 



NOTE 



if invoked with the ~T argument, rpcgen creates an additional output file 
that contains index information used for the dispatching of service routines. 



Once created, the server should be copied to a remote machine and run. (If the 
machines are homogeneous, the server can be copied as a binary. Otherwise, 
the source files will need to be copied to and compiled on the remote machine.) 
For this example, the remote machine is called remote and the local machine is 
called local. The server is started from the shell on the remote system: 
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Server processes, like msg__server, created with rpcgen always run In the 
background. It is not necessary to follow the server's invocation with an 
ampersand (&). Servers generated by rpcgen can also be invoked with 
port monitors like listen and inetd, instead of from the command line. 

Thereafter, a user on local can print a message on the console of system 
remote as follows: 




Using rprintmsg, a user can print a message on any system console (including 
the local console) if the server msg_server is running on the target system. 



Generating XDR Routines witli rpcgen 

The previous example illustrated the automatic generation of client and server 
RFC code, rpcgen may also be used to generate XDR routines, i.e., the rou- 
tines necessary to convert local data structures into XDR format and vice-versa. 

This example presents a complete RFC service: a remote directory listing ser- 
vice, built using rpcgen not only to generate stub routines, but also to generate 
the XDR routines. 

Here is the protocol description file: 



6-12 



Programmer's Guide: Networking interfaces 



An rpcgen Tutorial 



* dir. XI ttoot^ dir^etory listing pt<it&6oX 

coMt mxmmm * asS; maxlwum length of « dljjectojy «itry */ 

ty^>edBf string naraBtype<MA)CMJtt4&L&M>; /* a dlxdctozy antJ^y ^^Z 
ty|>dddf stztkct naMenode ^n^uMellat; A link In the llartlng ^/ 

liiililllilllllll^ 

* A node in the dl>?ectoKy lifting 

iiiliiiiii^^^ 

struct namenode { 

nametype name; 
namellst next; 

* IXie result of a IREWDDIR ojjeration. 

liiiiiiB^^^ 

union readdirjines switch (int ermo) { 
case 0: 

namelist list; /* no error; return directory listing */ 

default; 

void; /* error occurred: nothing else to return */ 



/♦ name of dlrectoi;y ontjy */ 
next entry */ 



* The directory prograjn definlti<»> 

program DIFEPBOG { 

Version htS^J^^ ( 

xeaddir^res 
^EAti^XIKnametype) ^ 1; 

) - 

y * 0x20000076; 



I Types (like readdir_res in the example above) can be defined using the 

NOTE struct, union and enuxn keywords. These keywords should not be used 

in later declarations of variables of those types. For example, if you define a 

I union fop, you should declare using only f oo and not union foo. 

rpcgfen compiles RPC unions into C structures. It is an error to declare 
RPC unions using the union keyword. 



rpcgen Progrannming Guide 



6-13 



An rpcgen Tutorial 



Running rpcgen on dir . x creates four output files. First are the basic three 
described previously: those containing the header file, client stub routines and 
server skeleton. 

The fourth contains the XDR routines necessary for converting instances of 
declared data types from host platform representation into XDR foramt, and 
vice- versa. These routines are output in the file dir_xdr . c. 

For each data type used in the .x file, rpcgen assumes that the RPC/XDR 
library contains a routine whose name is the name of the datatype, prepended 
by xdr_ (e.g. xdr_int ). If a data type is defined in the . x file, then rpcgen 
generates the required xdr_ routine. 

If there are no such data types definitions, in an RFC source file (e.g. msg.x), 
then an _xdr . c file will not be generated. 

An RFC programmer may write a . x source file that uses a data type not sup- 
ported by the RFC/XDR library, and deliberately omit defining the type (in the 
. X file); if so, the programmer has to provide that xdr_ routine. This is a way 
for programmers to provide their own customized xdr_ routines. See the 
"Remote Frocedure Call Frogramming Guide" chapter for more details on pass- 
ing arbitrary data tj^s. 

Here is the server-side implementation of the RE ADD I R procedure. 
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* dirjp£6e.et t»mOt^ z^dddir ilii|!>l(glnetitatlon 



/* cheated by rpcsgen */ 



#i.))Cludd <tpc/xpc.h> 
linclude <dix»nt.l3> 
♦include '^dlr.h'* 

extern Int ermo; 
extern <shar *roalloc(>; 
extern char *»trdiip(>; 

readdir^res * 
3?eaddlr_X <dlma3nne) 

nametype ^dizname; 

iiiiiiiiiiii^liil^ii 

D3Cft ♦dixf>; 
9trtxct dir^t ''^d; 
nameXlst nX; 
iidmeXist *nlp^ 

atatic re^wadlr res res; /* imiat be ntMtid */ 



* open directory 
*/ 

dirp opendir(*dirnaiiie>; 
if (dirp — WLX.) ( 

3^es.e3^md >* ezztiCt^ 

return (Area); 

|g|ii||;|ilill|;^ 

* Free previous result 
*/ 

xdr free(xdr readdir res, &res); 



* Collect directory entries, 

* Memory allocated here will be freed by xdr_free 

* next time readdir__l is called 

nip * Sres.readdirjcesja.list; 
%diile (d - rBaddir7dirp>> { 

nl - *nlp - (najftenode *) »alloc(sia5eof (najn^iodeU i 

nl-^iame »• strdup (d->djrLame) ; 

nip - *nl->next; 

*nlp « NKLL; 



(continued on next page) 
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lllilliilllllllilliili 

dosedir (dlxp) ; 



Here is the client side program to call the server: 



iiliiiiiililiiiiiiiiiiiiiii 

rls.c: Remote directory listing client 



lincltjde <stdio.h> 
♦include <rpc/rpc.h> 
♦include **dir,h* 

extern int ermo; 

TnainCargc, angv) 

ittt argc; 



/* always need thi» */ 

/* will be generated JDy tpcgen */ 



CLXBHT *0X; 

char ^server; 
char Mir; 

readdir_res *re«ult; 
nasnellst nli 

if (argc !- 3) { 

fprltttf (dtderr, **Ujiage: %si host directoryXn**, 

ai9v{01>; 
exltd); 

iiiiiiili 



(continued on next page ) 
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iiiiiiiiiiiiiiiiiiiiiiiiii 

* exeats clieiit ''hauradl^'' useci for calling MBSSAGEPHX? on the 

* sQirver <aa9ignated on the coirmand Un©. we tell the RPC package 

* td ttte any id.aiible transport contacting the server. 

el * clntjcreateCaerver^ DIREROG, DiSVERS, ^'visible'^h* 
if (cl — '1toe»> I 

lllllllllllllllllllllll^ 

* Couldn't establish connection with server^ 

* Print error message and die* 

iiiiiiiiiiiliiiiiiiiii 

dntjpcreateerror (server) j 



ejdta); 



* Call the remote prooedare readdir on the server 

llllllllllllllllll 

result - readdir_l(tdir, ol>; 
If (result — mtX) { 

llllllilillllllllllli^^ 

* An error occurred vihlle calling the server. 

* Print error inessage and die. 

cilnt_perror(cl#^ server); 
exitd); 

illlllllllllllll^ 

♦ Okay, we successfully called the remote procedure. 

Illllllillllilllllll^^ 

if (result^>erxno 0) { 

lllllllllllllllllllll^ 

* A remote system error occurred < 

* Print error nessage and die. 

ermo * result->ermo; 

perror(dlr); 

exit<l>; 

ililliiiiilililillliiiililli 
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* Successfully got a dlwrtory listing. 

* Print it out. 

for (nl rasult->ztii^lrjMiSjii.iidt;! nl !»• KOtt; 



Again using the hypothetical systems named local and remote, the files can 
be compiled and run as follows: 













remote? ipcgen cUr.x 
remote$ oC *-c dir^xdr.c 

remote$ cc rls^c dlr_clnt*c dir^jodr.o -o rls 
remote? cc dir^svc.c dirjf>roc.c dlrjcdr.o -o 


-Insl 

dlrjsve -Xnsl 




remote? dlr svc 

V 








J 



After installing an executable copy of rls on system local, a user on that sys- 
tem can list the contents of /usr/share/lib on system remote as follows: 
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^qnqhar 

kbd 

tabcar 

tabid 

tabs4 



Using Preprocessing Directives 



The rpcgen compiler supports C and other preprocessing features. 

C-preprocessing is performed on rpcgen input files before they are compiled. 
All C-preprocessing directives are legal within a . x file. Five symbols may be 
defined by rpcgen, depending on the type of output file being generated. The 
symbols are: 



Symbol 



Usage 



RPC__HDR For header-file output 

RPC__XDR For XDR routine output 

RPC_SVC For server-skeleton output 

RPC_CLNT For client stub output 

RPC_TBL For index table output 



The rpcgen compiler provides an additional preprocessing feature: any line 
that begins with a percent sign (%) is passed directly into the output file, 
without any interpretation of the line. 
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spAunoN/ 



The % feature is not always useful, owing to a limitation: The rpcgen 
compiler may not place the lines where the programmer intended. 



Here is a simple example that illustrates rpcgen preprocessing features: 



* tlme.x: Peinote time protocol 

iiiiiiiiiiiiiiiiiiiiiiiiiiiiii 

version TJMEIVERS { 

Wttdigned int TIMBGET (void) ^ 1? 

Illiiiiiilillliiiililli^ 

} * 0x20000044; 

lifdef BPC^SVC 
%int * 
%timeg©t K) 



% 
% 
% 
% 



static int thetirae; 

thetiina m tljn6<Q); 
ixxstumx^Ath^tlmey;;:::: 
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This section suggests some 
network types 

timeout changes 
authentication 

define statements 

broadcast calls 

port monitor support 
dispatch tables 
debugging 



coding and rpcgen usage techniques. 

rpcgen can produce for specific transport types 
(or even specific transports) 

client default timeout periods can be changed 

clients may authenticate themselves to servers; 
interested servers can examine client authentica- 
tion information 

C-preprocessing symbols can be defined on 
rpcgen command lines 

servers need not send NULL replies to broadcast 
calls 

p)ort monitors can "listen" for RPC servers 

programs can access server dispatch tables 

clients and servers created with rpcgen can be 
linked and run on a single system for debugging 
purposes 



isietwork Types (transport selection) 

The rpcgen compiler takes optional arguments that allow a programmer to 
specify a desired network type or even a specific network identifier. (For details 
about network selection, see the "Remote Procedure Call Programming Guide" 
chapter.) 







m 


3TE 



In the context of RPC programming, the term network is frequently used (as 
here) as a synonym for transport or transport type. 



The -s flag creates a server that responds to requests on all transports of a 
specified type. For example, the invocation 

rpcgen -s datagrain_n prot.x 

writes a server to standard output that responds to any of the connectionless 
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transports specified in the NETPATH environment variable (or in 
/etc/netconf ig, if NETPATH is not defined or does not specify any connec- 
tionless transports). 

Similarly, the -n flag creates a server that responds only to requests from the 
transport specified by a single network identifier. 

^® careful using servers created by rpcgen with the -n flag. Because 
network identifiers are host-specific, the server produced may not run on 
other hosts in the expected way. 



Timeout Changes 

After sending a request to the server, a client program waits for a default 
amount of time (25 seconds) to receive a reply. This timeout may be changed 
using the clnt_control () routine. [See rpc(3N).] 

When considering timeout periods, be sure to allow for the minimal 
amount of time required for "round trip" communications over the net- 
work. 




Here is a small code fragment to illustrate the use of clnt_control () : 



struct tliteval tv; 
CLIENT *cX; 

cl cXtttj5J?eatd(-aiomehosf> SOMEPBDG, SOMBVERS, ^'vidlbXe*') ; 
If <g1 ^ NOti.) ( 
exit(l); 

tv.ty_soG ^0; /* change timeout to 1 minute ♦/ 
tv,tyji5ec - 0; 

clntjsontrol (clr CLS&T^TlME(XJT^ &tv) ; 
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Client Authentication 

The client create routines do not, by default, have any facilities for client authen- 
tication, but the client may sometimes want (or be required) to authenticate 
itself to the server. Doing so is trivial, and looks about like this: 

The following example illustrates one of the least secure authentication 
methods in common use. See the "Remote Procedure Call Programming 
Guide" for information on the more secure DES authentication technique. 



^iillllill^^aElMliiil 

CLIENT *cl; 

cl cllentj?r9at^("sora^oat"r SOMEPHOQi^ SOMEWERS, "vlalble**); 
if {cl MOn.) { 

/♦ !Eo s^t ADtttJSra style attthentlcation */ 

I' " ) 

Servers that want to know more about an RPC call can check authentication 
information. For example, getting authentication information is important to 
servers that want to acfdeve some level of security. This extra information is 
actually supplied to the server as a second argument. (For details, see the struc- 
ture of svc_req, in the "Authentication" section of the "Remote Procedure 
Call Programming Guide" chapter. 

Here is an example of a remote procedure whose server checks client authenti- 
cation information. This is a rewrite of the printmessage_l 0 that is 
developed in the "An rpcgen Tutorial" section. The rewritten procedure will 
only allow root users to print a message to the console: 
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int * 



char ♦♦nisg; 

»txuet avcj:«j ♦rq; 

static int xesnlt; /* Mut be static ♦/ 

struct authsys^pazms *^aup; 

aup * (struct authsysj^azms *)xq~>rq_clntczed; 
if <aup->aupjaid I- 0> { 



result 0; 
return (iresuXtU 



} 



* Sama code as before. 



rpcgen Command-line Define Statements 

The rpcgen compiler provides a means for defining C-preprocessing symbols 
and assigning values to them from the command line. Command-line define 
statements can, for exiample, be used to compile conditional debugging code 
that is compiled only when the DEBUG symbol is defined. For example: 



















proto 



6-24 



Programmer's Guide: Networl(ing interfaces 



Common RPC Programming Techniques 



Server Response to Broadcast Calls 

When a procedure is known to have been called via broadcast RPC, and the 
called procedure determines that it cannot provide the client with a useful 
response, it is usually best for the server to send no reply back to the client. 
This reduces network traffic. 

To prevent the server from replying, a remote procedure can return NULL as its 
result. The server code generated by rpcgen will detect this and not send out 
a reply. 

Here is an example of a procedure that replies only if it thinks it is an NFS 

server: 

char notnlill; /* ^ust hare so Ma can lise its address ^/ 

if (access ("/etc/esqpoxts'', FJOK) < 0> ( 

return (NDUiy; /* prevent BPC frcm replying */ 

* assign nofnull a non^'nuj.l value so RPC will send out a r^ly 
return ((void *)finotnull); 

V J 




If a procedure returns type void it must return a non-NULL pointer if it 
wants RPC to send a reply. 
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Port Monitor Support 

Port monitors such as inetd and listen can monitor network addresses for 
specified RPC services. Whenever a request comes in for a particular service, 
the port monitor spawns a server process to provide for it. After the call has 
been serviced, the server can exit This has the advantage of conserving system 
resources: fewer blocked processes waiting for work. 

It may be useful for services to wait for a specified interval after satisfying a ser- 
vice request, on the chance that another request will follow. If there is no call 
within the specified time, the server will exit and some port monitors, like 
inetd, will continue to monitor for the server. If a later request for the service 
occurs, the port monitor will give the request to a waiting server process (if 
any), rather than spawning a new process. 

When monitoring for a server, some port monitors, like listen, always 
spawn a new process in response to a service request. If it is known that 
a server will be used with such a monitor, the server should exit immedi- 
ately on completion. 

By default, services created using rpcgen wait for 120 seconds after servicing a 
request before exiting. The programmer can, however, change that interval with 
the -K flag. 

Here the server will wait only for 20 seconds before exiting. To create a server 
that exits immediately, -K 0 can be used. To create a server that never exits (a 
normal server), the appropriate argument is -K -1. 

All servers generated by rpcgen assume the following support from port moni- 
tors: 

■ the name of the transport provider is passed through the environment 
variable NLS_PROVIDER 

■ the connection is passed on an open TLI file descriptor 0 
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See the "Using Port Monitors" section of the ''Remote Procedure Call Program- 
ming Guide" chapter for a further discussion of port monitors. 



Dispatch Tables 

It is sometimes useful for programs to have access to dispatch tables used by the 
RPC package. For example, the server dispatch routine may need to check 
authorization and then invoke the service routine; or a client library may want 
to deal with the details of storage management and XDR data conversion. 

When invoked with the -T option, rpcgen generates RPC dispatch tables for 
each program defined in the protocol description file, proto . x, in the file 
protojcbl . i. For sample protocol description file, dir . x, given in the "Gen- 
erating XDR Routines with rpcgen" section, above, a dispatch table file created 
by rpcgen would be called dir_tbl . i. The suffix . i stands for "index." 

Each entry in the dispatch table is a struct rpcgen_table, defined in the 
header file proto . h as follows: 



aittuct rpcgenJtabXe { 



char 

xdrproc^t 

unsigned 

acdrprocj: 



♦ (*proc) (); 
ten xida; 



where 

proc 

xdr_arg 

len_arg 

xdr_res 

len res 



is a pointer to the service routine, 

is a pointer to the input (argument) xdr_ routine, 

is the length in bytes of the input argument, 

is a pointer to the output (result) xdr_ routine, and 

is the length in bytes of the output result. 
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The table, named dirprog_l_table for the example, is indexed by procedure 
number. The variable dirprog_l_nproc contains the number of entries in the 
table. 

An example of how to locate a procedure in the dispatch tables is shown by the 
routine f ind_j)roc () : 



f indjproc (pxoc) 

long prpc; 



i 



} 



if (ptoc >- dirpro^JLjapzOb) 
/♦ error ♦/ 

else 



Each entry in the dispatch table contains a pointer to the corresponding service 
routine. However, that service routine is usually not defined in the client code. 
To avoid generating unresolved external references, and to require only one 
source file for the dispatch table, the rpcgen service routine initializer is 
RPCGEN_ACTION (proc_ver) . 

This way, the same dispatch table can be included in both the client and the 
server. Use the following define when compiling the client: 





















f 

1 fdeflne BPCXsmjcTiois {routme) 


0 

















and use this define when compiling the server: 















#def ine RPGGSN 





mtUni 



J 
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Debugging with rpcgen 

When progranuning with rpcgen, the client program and the server prcx:edure 
can be tested together as a single program by linking them with each other 
rather than with the client and server stubs. To do this, calls to RPC library 
routines [e.g. clnt_create ()], have to be commented out, and client-side 
routines have to call server routines directly. The procedure calls will be exe- 
cuted as ordinary local procedure calls and the program can be debugged with 
a local debugger. After the program is working, the client program can be 
linked to the rpcgen-created client stubs and the server procedures can be 
linked to the rpcgen-created server skeleton. 
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RFC language is an extension of the XDR language. The sole extension is the 
addition of the program and version types. 

For a complete description of the XDR language syntax, see the "External Data 
Representation: Protocol Specification" chapter. For a description of the RPC 
extensions to the XDR language, see the "Remote Procedure Calls: Protocol 
Specification" chapter. 

RPC language is similar to C language. We describe here the S)mtax of the RPC 
language, showing a few examples along the way. We also show how the vari- 
ous RPC and XDR type definitions get compiled into C type definitions in the 
output header file. 

Definitions 

An RPC language file consists of a series of definitions. 

definition-list: 

definition ; 

definition ; definition-list 

It recognizes six types of definitions. 

definition: 

enum-definition 

const-definition 

typedef-definition 

struct-definition 

union-definition 

program-definition 
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Enumerations 

RPC/XDR enumerations have the same syntax as C enumerations. 

enum-definition: 

enxm enum-ident { 

enum-value-list 

} 

enum-value-list: 

enum-value 

enum-value , enum-value-list 

enum-value: 

enum-value-ident 
enum-value-ident = value 

Here is a short example of an RCP/XDR enum, and the C enum to which it gets 
compiled. 

enum colortype { enum colortype { 

RED = 0, RED « 0, 

GREEN = 1, — > GREEN » 1, 

BLUE = 2 BLUE = 2, 

>; }; 

typede£ enum colortype colortype; 



Constants 

RPC/XDR symbolic constants may be used wherever an integer constant is 
used, for example, in array size specifications. 

const-definition: 

const const-ident = integer 

For example, the following defines a constant, DOZEN, equal to 12. 

const DOZEN « 12; ~> #define DOZEN 12 
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Typedefs 

RPC/XDR typedefs have the same syntax as C typedefs. 

typedef'definition: 

typedef deckration 

Here is an example that defines an f name^type used for declaring file name 
strings that have a maximum length of 255 characters. 

typedef string fnaine_type<255>/ — > typedef char *fnaxne_type/ 



Declarations 

In RPC/XDR, there are four kinds of declarations. 

declaration: 

simple-dedaration 
fixed'array-declaration 
variable-array'declaration 
pointer-declaration 

Simple Declarations: Simple declarations are just like simple C declarations. 

simple-declaration: 

type-ident variahle-ident 

Example: 

colortype color; — > colortype color; 

Fixed-length Array Declarations: Fixed-length array declarations are just like C 
array declarations: 

fixed-array'declaration: 

type-ident variable-ident [ value ] 

Example: 

colortype palette [8]; — > colortype palette [8]; 
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Variable-Length Array Declarations: Variable-length array declarations have no 
explicit syntax in C. The RPC/XDR does have a syntax; it uses angle-brackets. 

variable-array-declaration: 

type-ident variable-ident < value > 
type-ident variable-ident < > 

The maximum size is specified between the angle brackets. The size may be 
omitted, indicating that the array may be of any size. 

int heights<12>; /* at most 12 items */ 

int widthsO; /* any number of items */ 

Because variable-length arrays have no explicit s)mtax in C, these declarations 
are compiled into struct declarations. For example, the heights declaration 
gets compiled into the following struct: 



} heights; 

Note that the number of items in the array is stored in the _len component 
and the pointer to the array is stored in the _val component. The first part of 
each of these component's names is the same as the name of the declared 
RPC/XDR variable. 

Pointer Declarations: Pointer declarations are made in RPC/XDR exactly as 
they are in C. Address pointers cannot really be sent over the network, but 
RPC/XDR pointers are useful for sending recursive data types such as lists and 
trees. The type is actually called "optional-data," not "pointer/' in XDR 



struct { 



u_int heights_len; 
int *heights_val; 



/* # of items in array */ 
/* pointer to array */ 



language. 



pointer-declaration: 

type-ident ^variable-ident 



Example: 



listitem *next; — > listitem *next; 



rpcgen Programming Guide 



6-33 



RPC Language Reference 



Structures 

An RPC/XDR struct is declared almost exactly like its C counterpart It looks 
like the following: 

struct'deftnition: 

struct struct'ident { 
declarationrlisi 

) 

declaration-list: 

declaration ; 

declaration ; declaration-list 

As an example, here is an RPC/XDR structure for a two-dimensional coordi- 
nate, and the C structure that it gets compiled into in the output header file. 

struct coord { struct coord { 

int x; — > int x; 

int y; int y; 

}; }; 

typedef struct coord coord; 

The output is identical to the input, except for the added typedef at the end of 
the output. This allows one to use coord instead of struct coord when 
declaring items. 



Unions 

RPC/XDR unions are discriminated unions, and look different from C unions. 
They are more analogous to Pascal variant records than they are to C unions. 

union-definition: 

union union-ident switch ( simple declaration ) { 
case-list 

) 

case-list: 

case value : declaration ; 

case value : declaration ; case-list 

default : declaration ; 
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Here is an example of a tj^ that might be returned as the result of a "read 
data" operation: if there is no error, return a block of data; otherwise, don't 
return anything. 

union read^result switch (int errno) ( 
case 0: 

opaque data [1024]; 
default : 

void; 

}; 

It gets compiled into the following: 

struct read_result { 
int errno; 
union { 

char data [1024] ; 
} read_result_u; 

); 

typedef struct read_result reader esult; 

Notice that the union component of the output struct has the name as the type 
name, except for the trailing _u. 

Programs 

RPC/XDR programs are declared using the following syntax: 
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program-definition: 

program program-ident { 

version-list 
) "Value 

version-list: 

version ; 

version ; version-list 

version: 

version version-ident { 

procedure-list 
) "Value 

procedure-list: 

procedure ; 

procedure ; procedure-list 
procedure: 

type-ident procedure-ident ( type-ident ) = value 

For example: 
/* 

* time.x: Get or set the time. Time is represented as seconds 

* since 0:00, January 1, 1970. 
*/ 

program TIMEPROG { 

version TIMEVERS { 

unsigned int TIMEGET (void) - 1; 
void TIMESET (unsigned) » 2; 

} = 1; 
} » 0x20000044; 

This file compiles into these #de fines in the output header file: 

tdefine TIMEPROG 0x20000044 
♦define TIMEVERS 1 
♦define TIMEGET 1 
tdefine TIMESET 2 
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Special Cases 

There are a few exceptions to the rules described above. 

Booleans: C has no built-in boolean type. However, the RPC library uses a 
boolean type called bool_t that is either TRUE or FALSE. Things declared as 
type bool in RPC/XDR language are compiled into bool_t in the output 
header file. 

Example: 

bool married; — > bool_t married; 

Strings: C has no built-in string type, but instead uses the null-terminated char 
* convention. In RPC/XDR language, strings are declared using the string 
keyword, and compiled into type char * in the output header file. The max- 
imum size contained in the angle brackets specifies the maximum number of 
characters allowed in the strings (not counting the NULL character). The max- 
imum size may be left off, indicating a string of arbitrary length. 

Examples: 

string name<32>; — > char *name; 
string longnameO; — > char *longname; 

Opaque Data: Opaque data is used in RPC/XDR to describe unt3^d data, that 
is, just sequences of arbitrary bytes. It may be declared either as a fixed or vari- 
able length array. Examples: 

opaque diskblock [512] ; — > char diskblockI512] ; 

opaque filedata<1024>; — > struct { 

u_int filedata_len; 
char *filedata_val; 
} filedata; 

Voids: In a void declaration, the variable is not named. The declaration is just 
void and nothing else. Void declarations can only occur in two places: union 
definitions and program definitions (as the argument or result of a remote pro- 
cedure). 
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Introduction 



The RFC package provides a multi-level application programming interface for 
development of network applications using remote procedure calls. 

At the simplified interface (the highest level), the package provides great tran- 
sparency, but offers only limited control over the underlying communications 
mechanisms. Program development at the simplified interface can be rapid, and 
is directly supported by the rpcgen compiler — a C-language code generator 
that supports remote procedure call program development. 



NOTE 



The "Generating XDR Routines with rpcgen" section of the "rpcgen Pro- 
gramming Guide" contains the complete source for a working RPC service: 
a remote directory listing service that uses rpcgen to generate XDR routines 
as well as client and server stubs. For most applications, rpcgen and its 
' facilities are fully adequate and the detailed information in this chapter is not 
required. 

Interfaces to lower levels of the RPC package provide increasing control over 
remote procedure call communications. Programs that exercise this control pay 
for the power in terms of greater complexity of code. Effective programming at 
the lower levels requires knowledge of computer network fundamentals. 

In order of increasing control and complexity, these levels are called the Top 
Level, Intermediate Level, Expert Level and Bottom Level. 

This chapter is intended for programmers who wish to write network applica- 
tions using remote procedure calls, and who want to use or understand the RPC 
mechanisms usually hidden by the rpcgen(l) protocol compiler. 



An Overview of the RPC Package 

The RPC interface can be seen as being divided into several distinct levels. The 
highest level is general, and provides for no fine control of any kind. The lower 
levels (four can be usefully distinguished) are available for use as necessary, and 
provide increasingly detailed levels of control. 
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NOTE 



For a complete specification of the routines in tlie RPC library, see the 
rpc(3N) and related manual pages. 



The Simplified Interface: Here, the programmer doesn't need to consider the 
characteristics of the underljdng transport, operating system, or other low-level 
implementation mechanisms. Programmers simply make remote procedure calls 
to routines on other machines, and need specify only the type of transport that 
they wish to use. The selling point here is simplicity. It is this level that allows 
RPC to pass the "hello world" test — that simple things should be simple. The 
routines at this level are used for most applications. 

Included in the simplified interface are only three basic RPC routines: 

rpc_reg() rpc_reg() registers a routine as an RPC routine and 

obtains a unique, system-wide procedure-identification 
number for it. 

rpc_call 0 Given such a unique, system-wide procedure-identification 

number, rpc_call () uses it to make a remote call to that 
routine on a specified host. 

rpcjDroadcast () Like rpc_call () , except that it broadcasts its call message 
across all transports of the specified type. 

The Top Level: At the top level, the interface is still simple, but the program- 
mer does have to create client and server handles before making a call. Like the 
routines in the simplified interface, the routines here require a nettype argu- 
ment that specifies a general class (type) of transports. 

The top level essentially consists of two routines: 

clnt_create () The generic client creation. The programmer tells 

clnt_create () where the server is located and the type 
of transport to use to get to it. 

svc_create () Creates server handles for all the transports of the 

specified nettype. The programmer tells svc_create () 
which dispatch function should be used. 
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The simplified interface and the top level of RPC, while simple, are also 
inefficient. They do not allow the choice of a specific transport (but see the dis- 
cussion of NTEPATH, below). At these levels, all routines just take a nettype 
argument, which serves to define the class of transport to be used. On the client 
side, programs do network selection, and hence may be slightly inefficient 
depending on the nettype. On the server side, programs may have to listen on 
many transports, and hence may waste system resources. 

In both of these cases, however, efficiency can be improved by judicious assign- 
ment to the NETPATH environment variable. If the programmer wishes the 
application to run on all transports, this is the interface that should be used. 

The Intermediate Level: The intermediate interface of RPC, and the two inter- 
faces below it, allow many details to be controlled by the programmer> and for 
that reason their use is necessary for special applications. Programmers should 
only go down to the level necessary for the control needed. Programs written 
at these lower levels are more complicated, but also more efficient. 

The intermediate differs from the two levels above it in that it allows the pro- 
grammer to specify directly the transport to be used. It consists of two routines: 

clnt_tp_create () Creates a client handle for a specified transport 

svc_tp_create () Likewise, svc_tp_create () creates a server handle for 
a specified transport. 

The Expert Level: The expert level consists of a larger set of routines with 
which the programmer can specify more parameters, but those parameters are 
still all directly transport related. It includes the following routines: 

clntjtli_create () Createis a client handle for a specified transport, allow- 
ing fine control of the client characteristics. 

svc_tli_create () Creates a server handle for a specified transport, allow- 
ing fine control of the server characteristics. 

rpcb__set ()/ Provides a programmatic interface to rpcbind, one that 

establishes a mapping between an RPC service and a 
network address. 

rpcb_unset ( ) Destroys a mapping of the type established by 

rpcb_set. 
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rpcbjgetaddr () 



Provides a programmatic interface to rpcbind, one that 
returns the transport address of specified RFC service. 



svc_reg() 



Associates a given program and version number pair 
with a given dispatch routine. 



svc_unreg() 



Destroys an association of the type established by 
svc_reg. 



The Bottom Level: The bottom level consists of routines called when the pro- 
grammer requires full control, even down to the smallest details of transport 
options. It consists of the following routines: 

clntjdgjcreate () Creates an RPC client for the specified remote program, 
using a connectionless transport. 

svc_dg_create () Creates an RPC server handle, using a connectionless 



clnt_vcjcreate () Creates an RPC client for the specified remote program, 
using a connection-oriented transport. 



Organization of Technical information 

'The Simplified Interface to RPC" section describes programming with RPC 
library-based services, and calling RPC functions using the simplest RPC inter- 
faces. Progranuning with arbitrary data types is also addressed. 

The next three sections serve as a general reference to the lower levels of the 
RPC package. 

'The Lower Levels of RPC" section illustrates the client- and server-side pro- 
gramming interfaces of each of the four lower levels of the RPC package;. 

The "Low-level Data Structures" section provides reference information on RPC 
handles and the authentication structure used for secure RPC communications. 



transport. 



svc_vc_create () 



Creates an RPC server handle, using a connection- 
oriented transport. 



/ 
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The "Low-level Program Testing Using Raw RPC" section describes pseudo-RPC 
interfaces that are provided by the package for testing purposes. 

The remaining sections focus on particular aspects of low-level RPC program- 
ming. 

The "Advanced RPC Programming Techniques/' comments on developing RPC 
applications programs th^t take advantage of the lower level interfaces. 

The "Advanced Examples" section illustrates how some important program- 
ming tasks are done using the RPC low-level interfaces. 
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The easiest interface to RPC does not require the programmer to use the inter- 
face at all. "RPC Library-based Network Services" describes using functions 
that hide all details of the RPC package. 

Some RPC services are not available as C functions, but are available as RPC 
programs. "Remote Procedure Call and Registration" shows how easy it is to 
use these services, and how easy it is to create new services that are equally 
simple to use. 

Data types passed to and received from remote procedures can be any of a set 
of predefined types, or can be programmer-defined types. "Passing Arbitrary 
Data Types" explains how such t5^s are declared and used. 

RPC Library-based Network Services 

Imagine writing a program that needs to know how many users are logged into 
a remote machine. This can be done by calling an RPC library routine, 
rusers () , as illustrated below: 
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# Include <t5tdio.h> 

iiiiiiiliiiiiiiiiii 

* A program that eaXls xuaexaO 

int argc; 
<jhar ♦♦argv; 

iiiiiliiiliiil^iiiiiiii^^ 

Int num; 



if (argc 2) { 

fprintf (stder?:^ "usage t %s hostnameVn'', a3xrv[0]); 
exit (1); 

if (inm - j:uaera<atgvHJ)> < 0) { 

fprintf (itdetJf, "^ror: ttiaettXn'*); 
exit^l); 

liiiiiilliiiiii;! 

print£("*d users on %s\n*, nura, azgvTl]); 
exit(O)? 



NOTE 



For rusers () to work, the rusers daemon must be running on the remote 
host. 



RPC library routines such as rusers () are in the RPC services library 
librpcsvc . a. Thus, the program above should be compiled with 

$ cc program. c -Irpcsvc -Insl 

Here are some of the RPC service library routines available to the C program- 
mer: 
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Routine 



Description 



rusers () 
rwalK) 
spray 0 



Return information about users on remote machine 
Write to specified remote machines 
Spray packets to a specific machine 



Remote Procedure Call and Registration 



The simplest interface to the RPC functions is based on the routines 
rpc_call 0 , rpc_reg 0 , and rpc_broadcast () . These functions provide 
direct access to the RPC facilities, and are appropriate for programs that do not 
require fine levels of control. 

Using the simplified interface, the number of remote users can be gotten as fol- 
lows: 
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f Include <tf«a/r|>ci.h> 



* ^ pjrograro that calX» the RUSCRSPROG JiPC jwogram 



mala(arge^ argv) 

iitt a£gc; 
char **aj:gv; 



unsicped Icng^ nusers; 
Int clnt^stat; 

if (arcfq l« 5) { 

If (cXnt^5tat - xpcjcaXX(atgvlXJ, 

HUSERSPBOG, RDSERSVERS, RUSBEtSPROC_NUM, 

xdr_vol<3, 0/ xdrji^Xong, fcnu»ers, "viclfcle'*) !- 0) { 

cXnt^permoCcXntjStat) ? 

exit(X); 

liiiiiiiiii^iiiii^iiiiiiiiiii^^ 

printf ("%d users on %a\nt*', nusers, argvCll); 
exit(O); 



The rpc callQ Routine 

The simplest way of making remote procedure calls is with the RPC library rou- 
tine rpc__call 0 . It has nine parameters. 

■ The first is the name of the remote server machine. 

■ The next three parameters are the program, version, and procedure 
numbers. Together, they identify the remote procedure to be called. 

■ The fifth and sixth parameters are an XDR filter for encoding and an 
argument that has to be passed to the remote procedure. 
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■ The next two parameters are an XDR filter for decoding the results 
returned by the remote procedure and a pointer to the place where the 
procedure's results are to be stored. 

■ Finally, there is the nettype specifier. 

Multiple arguments and results are handled by embedding them in structures. 
If rpc_call 0 completes successfully, it returns zero; otherwise, it returns a 
nonzero value. The return codes (of type enum clnt_stat, cast to an int in 
the previous example) are found in <rpc/clnt . h>. 

Because data types may be represented differently on different machines, 
rpc_call 0 needs both the type of, and a pointer to, the RPC argument (simi- 
larly for the result). For RUSERSPROC^NUM, the return value is an unsigned 
long, so rpc^call () has xdr_u_long () as its first return parameter, which 
says that the result is of type unsigned long; and finusers as its second 
return parameter, which is a pointer to where the long result will be placed. 
Because RUSERSPROC_NUM takes no argument, the argument parameter of 
rpc_call ( ) is xdr_void ( ) . 

If rpc_call () gets no answer within a certain time period, it returns with an 
error code. In the example, it tries all the transports listed in /etc/netconf ig 
that are flagged as visible. Adjusting the number of retries requires use of the 
lower levels of the RPC library, discussed later in this chapter. The remote 
server procedure corresponding to the above might look like this: 



r 

char * 
( 


Static unsigned Ipn^ 

iiiiiiiiiiiiiiiiiiiii; 


raisers 












■^ 


V 


} 


* C5ocle here to compute the number of users 

* and place result in v^idble misers. 

iiiliiiiiiiiiiiiiiiiiiiiiiiii^^ 

return ((char *>6nu8er9); 








J 
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It takes one argument, which is a pointer to the input of the remote procedure 
call (ignored in pur example), and it returns a pointer to the result. In many 
versions of C, character pointers are the generic pointers, so both the input 
argument and the return value are cast to char *. 



The rpc^regO Routine 

Normally, a server registers all the RPC calls it plans to handle, and then goes 
into an infinite loop waiting to service requests. If rpcgen is used to provide 
this functionality, it will generate much code, including a server dispatch func- 
tion and support for port monitors. But programmers can also write servers 
themselves using rpc_reg () , and it is appropriate that they do so if they have 
simple applications, like the one shown as an example here. In this example, 
there is only a single procedure to register, so the main body of the server 
would look like this: 

#4,nca«d© "<;»t<iio,W> 
linclucte <zpc9vc/ru9er9.h> 

matin <) 

5Vcjc«tt(K'' /♦ Jtevier j?efct«ctt5 */ 

fprintf C^tderr, "Error: svcjnm retumedl\n«>; 

\ J 

The rpc_reg {) routine registers a C procedure as corresponding to a given 
RPC procedure number. The registration is done for each of the transports of 
the specified type, or if the t3qpe parameter is NULL, for all the transports named 
in NETPATH. The first three parameters, RUSERPROG, RUSERSVERS, and 
RUSERSPRCX^__NUM are the program, version, and procedure numbers of the 
remote procedure to be registered; rusers is the name of the local procedure 
that implements the remote procedure; and xdr_void and xdr_u_long name 
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the XDR filters for the remote procedure's arguments and results, respectively. 
(Multiple arguments or multiple results are passed as structures.) The last 
parameter specifies the desired nettype. Note that, when using rpc_reg () , 
programmers are not required to write their own dispatch routines. 



NOTE 



The svc_run 0 routine is used at all levels of RPC programming. Strictly 
speaking, it does not "belong" to this or to any other level. 



After registering the local procedure, the server program's main procedure calls 
s vc_run ( ) , the RPC library's remote procedure dispatcher. It is this function 
that calls the remote procedures in response to RPC call messages. Note that 
the dispatcher in rpc_reg () takes care of decoding remote procedure argu- 
ments and encoding results, using the XDR filters specified when the remote 
procedure was registered. 

Passing Arbitrary Data Types 

In the previous example, the RPC call returned a single unsigned long. RPC 
can handle arbitrary data structures, regardless of different machines' byte ord- 
ers or structure layout conventions, by always converting them to a standard 
transfer syntax called External Data Representation (XDR) before sending them 
over the transport. The process of converting from a particular machine 
representation to XDR format is called serializing, and the reverse process is 
called deserializing. 

The type field parameters of rpc_call () and rpc__reg {) can name an XDR 
primitive procedure, like xdr_u_long () in the previous example, or a pro- 
grammer supplied procedure (that may take a maximum of two parameters). 
XDR has these "built-in" primitive tj^e routines: 



xdr_ 


_int 0 


xdr_ 


_u_ 


.into 


xdr_enum ( ) 


xdr_ 


longO 


xdr_ 


_^u_ 


_long() 


xdr__bool ( ) 


xdr_ 


short 0 


xdr_ 


_u_ 


short {) 


xdr_wrapstring 0 


xdr_^ 


char 0 


xdr_ 


_u_ 


char 0 
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The routine xdr_string() exists, but takes more than two parameters. It 
NOTE cannot, therefore, be used with rpc_call () and rpc_reg() , which only 
pass two parameters to their XDR routines. xdr_wrapstring ( ) has only 
two parameters, and Is thus OK. It, in turn, calls xdr^stringO . 

As an example of a user-defined type routine, if a programmer wanted to send 
the structure: 



stlruct aimpl^ { 
int a; 



} sinple; 



then rpc call () would be called as: 



r 



rpc__call (hostname, PPOQOi, VER3NUH, PBOCNUM, 
Xd3rj5inple* & simple 4..); 



where xdr simple () is written as: 



♦Inciude <rpc/rpc.h> 
llbeltide "siiinple.h" 

xdrjsln^le (aoclrsp, slnplep) 

stzudt silnple ^diinplepj 



( 



if (l3cdr_ittt(«irap, wi»pl^p->a)) 

zetuzn (f'ALSE}; 
if (!xidr_short(«lrsp/ &»linplep-'>to) ) 

a?&tujti {FALSE); 
return (TROE); 
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An XDR routine returns nonzero (true in the C sense) if it completes success- 
fully> and zero otherwise. A complete description of XDR is provided in the 
"External Data Representation Standard: Protocol Specification" chapter. Note 
that the above routine could have been generated automatically by using the 
rpcgen compiler. 

In addition to the built-in primitives, there are also some prefabricated building 
blocks: 



xdr_array 0 
xdr_vector () 
xdr_string() 



xdr_bytes () 
xdr_union() 
xdr_opaque () 



xdr_reference () 
xdr_|>ointer () 



To send a variable array of integers, the array might be packaged as a structure 
like thiis: 



struct varitttarr ( 
int *data; 



and sent by an RPC call such as: 



£pcGall(h6dtAam&, PPOl3StM, ymSttfM, £>£tOCNt]M, 
ao(irjrarintaxr« (axr^^.); 



with xdr varintarr () defined as: 
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booXJ: 

XDR *aDdrsp; 

5trttct varintarr *arrp; 



{ 



} 



retxixn (xidr^array(xdrsp,^ tarrp->data, Aarrp->arrXnthr 
MMCLEN, aii6o£<int), xdr^int)); 



The xdr__array 0 routine takes as parameters the XDR handle, a pointer to the 
array, a pointer to the size of the array, the maximum allowable array size, the 
size of each array element, and an XDR routine for handling each array element. 

If the size of the array is known in advance, one can use xdr_vector () , which 
serializes fixed-length arrays. 











mt intarrisiaej; 






hooi t 








»lr_intarr(xdrdp, intarr) 








XDR *xdrsp/ 



int intarr []; 

return (xdUr_vi8Ctor(xdrsp, intarr, SIZE, alzeof (int) , 
xdr^int)); 



XDR always converts quantities to 4-byte multiples when serializing. Thus, if 
either of the examples above involved characters instead of integers, each char- 
acter would occupy 32 bits. That is the reason for the XDR routine 
xdr_bytes () , which is like xdr_array () except that it packs characters; 
xdr_bytes {) has four parameters, similar to the first four parameters of 
xdr__array 0 . 

For null-terminated strings, there is the xdr_string() routine, which is the 
same as xdr_bytes 0 without the length parameter. On serializing it gets the 
string length from strlen () , and on deserializing it creates a null-terminated 
string. 
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Here is a final example that calls the previously written xdr_simple () as well 
as the built-in functions xdr_string () and xdr_ref erence () , which chases 
pointers: 



9t;£UGt finaleaeanple ( 
} flnalexaraplQ; 

struct f inali^xairplQ ^flnalp; 



{ 



xetiim (1RDE); 



Note that we could as easily call xdr__simple () here instead of 
xdr reference () . 
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In the examples given for programming at the simplied interface, RPC takes 
care of almost as many details as would the rpcgen compiler. RPC does so by 
choosing defaults for almost everything, including the transport protocol. 

This section shows how to control these details by using lower levels of the RPC 
library. The reader is assumed to be familiar with the Transport Level Interface 
(TLI). 

There are several reasons for using lower levels of RPC: 

■ A program may need to directly control the selection of the transport pro- 
tocol, which at the simplified interface level, can be done only by use of 
the NETPATH variable. 

■ A program may need to allocate and free memory while serializing or 
deserializing with XDR routines. There are no facilities for doing so avail- 
able at the higher level. (For details, see "Memory Allocation with XDR" 
in the "Advanced Examples" section of this chapter. 

The following sections illustrate programming at the lower levels of RPC. 

"The Top Level" describes RPC interfaces that allow for control of transport 
selection by tj^e. 

"The Intermediate Level" section describes those interfaces that allow a pro- 
grammer to choose a specific transport. 

"The Expert Level" section describes routines that: 

■ allow program control of client and server characteristics 

■ provide an interface to rpcbind 

Finally, the section on "The Bottom Level" describes routines that control most 
details of transport options. 

For detailed descriptions of RPC routines, see rpc(3N). 
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The Top Level 

At the top level, the application can specify the type of transport that it wants to 
use, but not an individual transport. This level differs from the simplified inter- 
face to RPC in that the application is responsible for creating its own transport 
handles, on both the client and server sides. 

Top Level: The Client Side 

Assume we have the following header file: 



gg|||||||||||||||||:| 

* time j)rot,h 

finclDdd <xpe/t^pea.h> 

5tract tiniev { 

Int. minute; 
int hour; 

u 

typecief struct timev tlmev; 

booljt xdrj:iiiiiev(»dr3p, reap) 
XDR *xdrop; 
sttuct titnev *xesp: 



{ 



i£ (!ac<aj:_lnt(xdr»p^ firesp'->30C<xid) > 

return (FAL£^); 
if (lxdr__int{xdrspr irBsp->iTdnute) ) 

return <FADSE); 
if (!xdr_int<xdr5p, tresp->hour) ) 

return (FALSE); 
return (ITRDE); 



#define T3«BJ>R06 ((uJ.ong)76) 
Idefine TIMEJVER5 ((uJ.ong)l> 
♦define TIMEJSET ((u_Xong)l) 



The following code implements the client side of a trivial date service, written at 
the top level: 



7-18 



Programmer's Guide: Networking Interfaces 



The Lower Levels of RPC 



flncludd <:dtdlo.h> 
l4nca«<Je '•tiitiejppot .h" 

Ic^f Ine TQTKL (30) 



^ Caller q£ trivial date service 
* wiage: <!aXltiitie hostname 

main (axgc/ aa?gv> 

Int argc; 
qhar ^^argvH; 

iiiiiiiiliilliiiliiiiiiiil^^ 

sttuct titndnral tiHiddiat^ 
CLIENT ^cilient; 

enum clnt^stat dtat; 
iitruct timdv timsv^' 
char *nettype; 



if (azgc !«* 2 && axgq $> { 

fprintffstderr/^usage: %s host lnettype]\n"*a?gv[0]>; 

if (argc ^ 2\ 

nettype - "netpath"; /* f)e£alilt V 

eXse 

nettype ^ argvfaj; 

qlient >« olnt^cieateiargvClJ, TIMEJPROG, TIME_VERS,. 

nettype) ; 
if {client — NOli) ( 

Clnt^,pcreateerror( "Couldn't create client" )|^; 

exit 

timeout »tv^sec - TOTftlr; 
tinieout.tvjusec - 0; 

Stat *• clnt_call (client, TIMEJGET, xdr_void, NULL, 

xicUM:imev, Atimev^ timeout); 
if (Stat t« W?C_SUC3CESS) ( 

cliit,j>error (client, "Call failed"); 

eadt(l); 

printf ("%s: %02<J:%02cl;%024 OffVn"^ nettype/ tiwev^hour, 

tljnev, minute, tijuev. second); 
exit(O); 

V ) 
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Note that, when this program is run, if nettype is not given on the command 
line, the code assigns it to point to the string "netpath". Whenever the rou- 
tines in the RPC libraries encounter this string, they consult the NETPATH 
environment variable for the user's list of acceptable network identifiers. 

If the client handle cannot be created, the reason for the failure can be printed 
using clnt_pcreateerror () , or the error status can be obtained via the glo- 
bal variable rpc_createerr. 

After the client handle is created, clnt_call () is used to make the remote 
call. It takes as arguments the remote procedure number, an XDR filter for the 
input argument and the argument pointer, an XDR filter for the result and the 
result pointer, and the time-out period of the call. Normally, this last should 
not be 0 . In this particular example there are no arguments, and thus 
xdr__void ( ) has been specified. 



Top Level: The Server Side 

Here's the code for the time server: 



♦Indtade <»tdio.h> 
flnclucte <rpc/rpe.h> 

static void tlroej>rog{); 

inain (argc, argv) 

ittt aj?gc; 



char *argvt3; 

int tacanapnum; 
<shar *nettype; 

if (argc — 2) 

nettype - argvEl]; 

else 

nettypG "netpath"; /* Default */ 

txanapnmn - 3vc_create(ti»e_j>rog* TIME_^PROG, TIME_VERS# 

tt^ttype); 
if (transpnum Q) { 

fprlntf (5t<3err,''%s; cannot create %» service. \n"* 
argvIOJ, nettype); 



(continued on next page) 
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) 

avojFunO; 



* ^nid 6BJfwr dispatdti funcitlon 
atatic void 

time^jirog<rqstp, transp) 

struct svcj?©q *rq5tp; 
SVCXRRT *transp; 

struct tiittev rait; 
long thetlin^; 



switch <rqstf>->rqjproc) { 
case ISIUZJJPBDC: 

svc^sendxeplyCtransp, xdr^yold* NOLL); 

return; 



case TIMEjGET: 
break; 



<Jefault: 

svcerrjioproc (transp) / 
return; 



thetime - tline(O); 

rslt. second « thetinte % 60; 

thetime 60; 

rslt .minute - thetime % 60; 

thetime 60; 

rslt .hour - thetime % 24; 

if (I svc_aendr^y<transpy aodrjtim^v, *rslt)) I 
svcerrjBystemerr (transp) ; 

iiiliiiliiiliiiiii 

wmmmmmmmmmmmmM^ 

J 

svc__create () returns the number of transports on which it could create 
server handles. time__prog () is the dispatch function called by svc_run () 
whenever there's a request for its given program and version number. 
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Here the remote procedure takes no arguments. Had arguments been required, 

svc_getargs (transport, XDR__filter, airgument_pointer) 

could have been used to deserialize (XDR decode) the arguments. In such cases, 
svc_£reeargs () should be used to free up the arguments after the actual call 
has been made. The server reply resiilts are sent back to the client using 
svc_sendreply 0 . 

it is recommended that rpcgen be used to generate the dispatch function which 
can later be customized. 

When rpcgen is used to generate the dispatch function, 
svc_sendreply () is called only after the actual procedure has 
returned, and hence it is essential to have rslt (in this example) 
declared as static within that actual procedure. 

In this example, rslt is not declared as static because svc^isendreply () is 
called from within the dispatch function. 

The Intermediate Level 

At the intermediate level> the application directly chooses the transport it wishes 
to use, factoring the value of NETPATH and the contents of /etc/netconf ig 
into the choice as it sees fit 

Intermediate Level: The Client Side 

The following code implements the client side of the same time service shown 
above, but written to the intermediate level of the RPC package. 

Here, the programmer requires the user to name, on the command line, the 
transport over which the call will be made: 
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lljicludd <dtdio.h> 
f InctludA <t]|)6/rp6.h> 

#4,ncawie <net<30nfig>h> J* For xmtooxitiq structure */ 

# include **ti«i(e|j>xot.h*' 

♦define TOT?«:. (30) 

i^iiiiiiiii^i^iiiiiiiiiiii^ 

* CalXer of trivial date service 

* usage: calltiioe hostname netid 

iiii^iiiiiiiiiii^iiiiiiiiiiiii 

inain(argc,argv) 

int argc; 
char *argvij; 

struct netconf ig *ncon£; 

/* Declarations from previous example */ 

if (argc r- 3) i 

fprlntf (stderr, "Tisagei %s host netld\n",argv[0]) ; 

nettype azgvt2]; 

if ((ttconf •* getnetopnf Igent (nettype) ) — NULL) { 

fprlntf (stdsrr, *Bad netid type: %s\n% nettype); 
exitd); 

1 

client - clntj:pjcreate(argv{l}, TIMBJ?J«5G, IIMBJ/BRS^ 

nccjnf ) ; 
If (client — { 

clntjx:reateerror( "Could not Create client**); 

exit (1); 

/* Sasoe as previous example after this point */ 

J 

The netconf ig structure can be obtained by a call to 

getnetconf igent (nettype) . (See getnetconf ig(3N) for more (details.) 

At this level, the program must explicitly make all decisions about network- 
selection. 
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Intermediate Level: The Server Side 

Here's the corresf)onding server. The administrator who starts the service is 
required to name, on the command line, the transport over which the service is 
provided: 



/* For netconf ig structure */ 



♦incXTJde <at<3io.h> 
♦include <cpc/xpc,h> 
linqlude '^etconfl9.h> 

static void tiiwtj>rog () ; 

/* Service to $i:¥)|>ly Gaceenvich ttem tism */ 
/* usage: setvet nfetid */ 

main (argc, argv) 

int argc; 
Char *argvn; 

llliilllilllllliillli 

Svc5fl?RT *traftap; 

struct netcottflg *txconf ; 

if targe ^ 1) { 

fprintf (stderr, "uaage; server net i<3 Vn") ; 
exit(l>; 

if ((nconf « getnetconf igent (argvtl j ) > NULL) { 

fpritttf (stderr, "Couad not firid info on %s\n", 

argvtll); 
exit(i>; 

llllllllllllllll^ 

transp • svcjfcpjcreate (tliftejprog, TIMBjeROG^ TWBjmS, 
noonf ) ; 

if (tranap NULL) { 

fprintf {3tderr,'*%s: cannot create %5 service An 

argv[03, argVEl]); 
exit(l> 

svcjcmO; 



static void 

tiitre^rog(rc(stp^ transp) 

struct svc^req *rqstp; 
SVCXPRT *tran3p; 



(continued on next page) 
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The Expert Level 

At the expert level, network selection is done exactly as at the intermediate 
level. The only difference here is in the level of control that the application has 
over the details of the transport's configuration. Control at this level is much 
greater. These examples illustrate that control, which is exercised using the 
clnt_tli_create 0 and svc_tli_create {) routines. 

Expert Level: The Client Side 

Here is the client side of some code that implements a version of 
clntudp_create () (the client-side creation routine for the UDP transport) in 
terms of clnt_tli__create () . The example shows how to do network selec- 
tion based on the family of the transport one wishes to use. 

clnt_tli_create () is normally used to create a client handle when: 

■ the application wants to pass an open file descriptor, which may or may 
not be bound 

■ the programmer wants to feed the server's address to the client 

■ the programmer wants to specify the send and receive buffer size (here, 
8800 bytes) 
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ilncXi^ <itdlo.h> 
llndludd <r|>c/z|>e.h> 
#lncJ.Ta<Je <iietconflg*h> 
fincXtadd ^<rua(tltuait/ln.h>' 

lillliilillllllllliiili^ 

* Jn m wti^ 4wpl6i«wit*tl0R ot V^, the ooly transports atipported 
vpe£« 1KP/1S^ «t)d tXX^/iP, Iteitvd th^y ftzi^ sh<Mn bASed the Berkeley 

* 9Qcki9%r l»ut Implemented en the top Of TLI/St reams . 
*/ 

cXntuti^je»?Mte(riiddr» prog, vers^ wait, socitp) 

sti?uct sockaddr^ttt *r«Jdr; /* B6»ote address ♦/ 
u^Xong prog; /* Program nunijer */ 



wjla*g vers; 

stxuet titndvaX Kait; 

int "*sockp; 



/* ^rsioR number */ 
/* lima to wait */ 
/* fd pointer V 



int madefd * FALSE; 
int fd «^ *sockp; 
struct t^bind *tbind; 
Struct netconf ig *ncoRf ; 
void '^handlep; 



/* Client handle */ 
/* Is fd op^^ here V 
/♦ M */ 

bind adcbresa V 
/* netconf ig structure */ 



if (<ha»dlep setneteonfigO) -^0) J /* No transports available */ 
rpejnreate^r.cfstat « ftPCJJNKNOWNPROTO; 
return ( ((XIBNT * ) NUIX) ; 



) 



Try nil the transports till it gets one ^ich is 
oonne<£tlOklXess, family is INBT and name is UDP 



nftiile Inemt - getnetconfig{handlep)) { 

if <(nConf->fic_seroantics — »C_TPIjCLtS) && 

(Btrcmp fnconf^>nc_protofinly, NC^INET) — 0) 4& 
(sftrc»|>(nconf-'>ttc_proto^ j«CJ3Dp7 — 0)) 
break; 

if (nconf KtlLL) { 

rpcjsreateerr^CfjSt&t BPCJQNKNQHHPPOTO; 
goto err; 



if 



(fd — RPCJMWSOCK) { 

fd •^t_open(nconf->ncdevice^ NOTX),* 
If (fd — -1) { 

rpc_createerr,cf_stat * RPC_SYSTEM»ROR; 



(continued on next page ) 
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^oto err; 

iiiiiiiiiiiiiiiiiiliiiiiii 

maaefd * THUB; /* Tl» fd urns 
i£ (xaidkirw>8iii^po£t 0> { /* x<wt9 adklr 






opened here ♦/ 




unknown */ 




illlllllllllllilllli^ 





* rpcbjaetport 0 l5 a twer provided routine 
^ which ^11 zpob^getaddr and translate 

* the netbJf address to port number, 

iiiliiiiiiiiiiiiiiiiiiiiii^iiii^^ 

sport * rpcbj3etport(raddr, prog, ^rs, nqqnf); 
it (sport — 0> { 

tpejsreateettf.efjitat Wcj'lsixxmNKiLt 

goto err; 

raddr->sin^^j>ort * sport; 



/* Transfom sockaddr_ln to netbuf */ 

tblud * (struct tj>lnd *yt_alloc(fdr TBUJD, TJVDDR); 

if (tblnd ^ JrolxT i ^ 

rpcjca?eateerr»df^stat * RPCJSYSTEMERROR; 

goto err; 

(void) inenK5)y(tl5lnd->adclr,buf, (cdiar *)raddr^ 

(int ) tbind-'>adde .iwoclen) ; 
tbiiid->addr4 len » tblnd->addr.maxlen; 



/* Bind enc^int to a reserved address */ 
(void) bind_resv(fd>; 

cX ^ clntj:lijt3reate<fdy nconf, « (tbind->addr) * pw>g, 

vers, 8800, 8800); 
(void) endnetconfig<hanaiep>; /* Close the netconfig file */ 

(void) tjrree((dhar *)tblnd^ tBU©); 
if (ci) T 

♦sociq> * fd; 

if (madefd ^ TRUE) { 

/♦ fd should be closed while destroying the handle */ 

(void) amjxmscLiQi, <xsBTj?ojctosE, mL); 

iiiiiiiiiiiiiiiiiiiiiiiiiiiiii 

/* Set the tetry tim V 

(void) cmtjmmt,(ci, cxssTj^imjrMotrr, «wait); 

return <cl); 

iiiiiiiiiiiiiili^^^ 

v,^ J 

(continued on next page ) 
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if (madef <J mm 

<void) tjcsJodd^fd) ; 
(voi4) enG|net:conf (hondlep) ; 
y^tum ((CLIENT *>Hm;i.); 

V J 

The network selection is done using the library functions setnetconf ig () , 
getnetconfigO , and endnetconfigO . (Note that endnetconfigO is 
not called until after the call to clnt_tli_create () , near the end of the 
example.) 

clntudp_create () can be passed an open fd, but if not (fd 
RPC_ANYSOCK) , it will Open its own using the netconf ig structure for UDP. 

If the remote address is not known, (raddr->sin_port =« 0), then it is 
obtained from the remote rpcbind. Note the call to bind_clnt__resv () , 
which serves to bind a transport endpoint to a reserved address. This call is 
necessary because there is no notion of a reserved address in RPC under TLI, as 
there is in both TCP and UDP. The implementation of this routine is of no 
interest here, because it is entirely transport specific. What is of interest is the 
scaffolding necessary to call it. 

After the client handle has been created, the programmer can suitably customize 
it using calls to clnt__control () . Here, the RPC library closes the file 
descriptor while destroying the handle (as it usually does with a call to 
clnt_destroy 0 when it opens the fd itself) and sets the retry timeout 
period. 

Expert Level: The Server Side 

Below is the corresponding server code. It implements svcudp_create () in 
terms of svc_tli_create () , and calls the user provided bind__resv () to 
bind the transport endpoint to a reserved address. 
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svc_tli_create () is normally used when the application needs a fine degree 
of control, and especially if it is necessary to: 

■ pass an open file descriptor to the application 

■ pass the user's bind address 

■ set the send and receive buffer sizes (here being set to 8800 bytes) 

The f d argument may be unbound when passed in. If it is, then it is bound to 
a given address, and the address is stored in a handle. If the bind address is set 
to NULL, and if the f d is initially unbound, it will be bound to any suitable 
address. 

It is the responsibility of the programmer to use rpcb_set ( ) to register the 
service with rDcbind. 



NOTE 



#ijiclude <dtdio.h>' 
♦include <rpe/rpc.h> 
♦incXyde <netconfig*h> 
♦include <netittet/ln.h> 

* On the server side 

iiiiiiiiiliiiiiiiiiiiil 

SVCXPRT * 
svcudpjsreate (f d> 

register int fd; 

i 



struct netconf ig *nqon£; 
SVCXPRT 

int inadefd «» ^KtS&j 
int pprt; 
void *lumdl^; 

it ((handler - setnetconf ig (>> — * 0) { /* No transports available */ 
nc_perror<*server'*) ? 
return ((SVCXPRT *)NDEL)f 

* Tr^ all the transports till it gets one trtiich is 



(continued on next page ) 
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u 




and mm 


> is TO 





(9trcnp(nQQnf^>nqj>rotQ^lyr NC^DET) 0> it 
(3trcnpCncoof'->fWLP?:oto# NCJtJDP) 0)) 

if (nc<»if ^ msL} { 

«tndndt6on£ig (haMl^) ; 

fprintf (atcterr^ ^ODP transport not availaia©\n*) ; 
return ((SVCXS^IW 

iiiiiiiliiiiiiiiiii^iiiiii 

if (fd -* RPCAHYFD> ^ 

(void) mdri/^tcMijgOi 
(TTOid) fp£int£<stddrrr 

"swcwdpjBijeat;©; could not open con»ection\»*> ; 

llllillllllll 

niadofd ^ ^SROS/ 



iiiiiiiiiliiiiliiiiiiiiiiili^^ 

^ Bind Endpoint to a reserved address 
port w biftdjcesv(£d>/ 

SVC » svcj;li_create(£d, nconf, (struct tj&ind *)NOII», 

8800, 8800); ^ 
(void) endnetconfigChandiep); 
if (SVC (SVC3CPRT *)HOLL) ( 

if (madefd) 

(Void) tjtaoae<fd)^ 
return ((STOCPRT *)Ut)LL); 

if (port — -1) 

/♦ Sipecif ically set xp_port now ♦/ 
ave->xpjport 

((struct sockaddr^in *)svc->xp_ltaddr.buf>->ainjport; 

else 

svc->xp^j»rt port;^ 
return (svc); 
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The network selection here is done in a similar way as in clntudp_create () . 

svcudp_create () is set up to receive an open fd, but if it does not, it will 
open one itself using the selected netconf ig structure. 

bind_resv () is a user-provided function that binds the fd to a reserved port 
if the caller is a superuser. 

The Bottom Level 

At the bottom-level interface to RPC, the application can control all options, 
transport-related and otherwise. clnt_tli_create () , and the other expert- 
level RPC interface routines are implemented on top of these bottom-level rou- 
tines. 

The programmer should not normally be using these low-level routines. 

These routines are responsible for creating their own data structures, their own 
buffer management, the creation of their own RPC headers, etc. 

Callers of these routines [like the expert level routine clnt__tli_create () ] 
are responsible for initializing the cl_netid and cl_tp fields within the client 
handle. The bottom level routines clnt_dg_create ( ) and 
clnt__vc_create() are themselves responsible for populating the clnt_ops 
and cl_j)rivate fields. 

For a created handle, cl_netid is the network identifier (e.g. udp) of the tran- 
sport and cl_tp is the device name of that transport (e.g. /dev/udp). 

Bottom Level: The Client Side 

The example here shows the use of local variables to control the exact details of 
the calls to clnt_vc_create () and clnt_dg_create () . Thus, these rou- 
tines allow control of the transport to the lowest level: 
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case %jxmjm>x 

Case tjClitSt 

ql « qlntj^^cz»ate (f d, svcaddr, prog, wrs. 



<lefaiiXt: 



goto exr; 



Bottom Level: The Server Side 

And, again, on the server side: 



call txanspozt specific funqticn^ */ 
switch (tlnf o . 9^rvtyp^> { 

xprt * $vc__vc_create (fa, »eixJ5z» xecvsz); 
brteak; 

case TjCI.2!S: 

xprt svcjdg^ciBate (f <J« 9end3z^ lecvsa); 
break; 

default: 

goto err; 
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For reference, here are the client- and server-side RFC handles, as well as an 
authentication structure. 

f \ 

* Client JTpc hwcJXe* 

■* Cxe«itdd by individual lintaeknantationd 

^ Client i9 responsible for initializing auth 

*/ 



typeddf Stzitcit { 

APTH *Gl^auth; /* authentlcator */ 

struct clntjops { 



enurti eltit^stat (*Cljcall) 0 ; 


/* 


call remote procedure ^/ 


void 


(*cX_abort) 0 ; 


/* 


abort a call */ 


void 


(♦cX^geteicrX); 


/* 


get specific erxror code */ 


booljt 


<*<5l_freeres) <); 


/* 


frees results */ 


void 


(*clj3estroy)<); 


/♦ 


destroy this structure */ 


bool^t 


(♦cljcdntrol) <); 


/* 


the ioctlO of rpc V 


) *ql__cp9; 








caddrjt 


cXjttrlvate; 


/* 


private stuff */ 


char 


*<sljietld; 


/* 


network token */ 


diar 


♦cljtp; 


/* 


device naine */ 


) CUEMT; 









The client-side handle contains an authentication structure. For a client pro- 
gram authenticate itself, it must initialize the cl_auth field to an appropriate 
authentication structure: 
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* Auth handle, int^rtad^ to Client side authentitiatdrd^ . 

typedef struct i 

struct opaqae^auth ahjpzecl; /* credentials */ 
Struct opaqae^auth ahjverf ; /* ^^if ieir */ 
tmioh dedj>lcck ^^^J^t CBS Jtey V 

struct authjc^s ( 

void (*ahjie5ttV(erfH>; 

int (^ahjnakrdhal} () ; /* lidztVI^ fi ititlilltiB V 
twt c*ajrralidate) (>; /♦ validate ve^iw */ 
int <*ahjtefacesh> (>; /* xefxiMh eredeaatials V 
void (^ahjUe^trpy) /* destroy thi? structure */ 

caddr]\ atkjarivatd; /* Private data 

) ADTH; 



Within the AUTH structure, ah_cred contains the caller's credentials, and 
ah_verf contains the information necessary to verify those credentials. (See 
"Authentication'' in the "Advanced RFC Programming Techniques" section for 
more details.) 



Here is the server-side transport handle: 
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lilllllilllliiii^ 

Int J9>^^<i; /* «39QCi«t6a Hie dwcrlptor */ 

u^ahort; «pjport** /* »990ci«t«KJ poirt number (obaolete) V 

atzticib j^^<)>pa { 

)>Ool_t t*3(pjc»cv) 0 ; /♦ receive Inqcudng requests */ 

entm xpttjst$t <*xs>jstat) <); /* gt^ twaiaport atatus */ 
bodljt (*»pj0etat?$(a) 0; /* ar^uindiita V 

booXJ; C*^9M^y> 0 ; /* 9esnd reply V 
booXJt (♦3¥Lfteeexga) (>//* free man aaaocated for args V 
(*atl>jJe9trQy) (); /* <iestroy thla struct */ 

iftt ^ :S|>_ac)drIeA^ Xetigth of remote addr. dosblet^ ^/ 

char *3C|>^tp; /* transport provlcter <$aviae nam? */ 

Char *j^jRetid; /* netiiotJc token ♦/ 

struct netbuf "xp^ltaddr^^ /* local transport address */ 

struct netbxif xpjrtaddr; /♦ remote transport addreaa */ 

Char ^jcaddrtl63? /* rewrote address. Obsolete */ 

struct opaque^auth xpjverf ; /♦ rsw response verifier */ 

^svOfXcJi ^JS>1: /♦ private! for use by avc ops */ 

caddr3 ^Jp2; /* private t for uae by svc c3>ps */ 

ca<iWrj|; ^J^f /* private; for use by svc lib */ 



xp_f d is the file descriptor associated with the handle. Two or more server 
handles can share the same file descriptor. 

xp_netid is the network identifier (e.g. udp) of the transport on which this 
handle was created and xp_tp is the device name associated with that tran- 
sport. 

xp_ltaddr is the server's own bind address, while xp_rtaddr is the address 
of the remote caller and hence may change from call to call. 

xp_netid, xp_tp and xp_lt:addr are initialized by svc_tli_create () and 
other expert-level routines. 

The rest of the fields are initialized by the bottom-level server routines 
svc_dg_create () and svc_vc_create () . 



Remote Procedure Call Programming Guide 



7-35 



Low-level Program Testing Using Raw RPC 



There are two pseudo-RPC interface routines provided to support program test- 
ing. These routines, clnt_raw_create() and svc_raw_create(), do not 
involve the use of any real transport. They exist to help the developer debug 
and test the non-communications-oriented aspects of an application before run- 
ning it over a real network. 

Here's an example of their use: 



* A si»t>l<d pxfoqtm to ixictm&nt a ntawiber by 1 

#4ncXucle <»t<Jio.h> 
♦IncXucte <tpc/rpc,h> 
#inclvKje <rpcj/raw,h> 



struct tlneval TIMEOUT •» {0, 0); 
static voi4 server <); 

main (ar^cir axgv) 
Int argrc; 



^vdxPRT *svej 
int num •» 0, 



ans; 



if (at^c «^ 2) 

num * atoi (argv [1] ) ; 
SVC • Bvcjra>r_create(>; 

if (3VC NULL) { 

f prtntf (stderr, "Could not create server handleXn") ; 
exita>; 

;|||||||||||;||||||^ 

svc_reg(svc, 200000^ X, server^ 0); 
<:X«» clntjrawjcreate (200000, 1); 
if (cl — "InXCX) { 

cXntjpcreateerror (♦*raw") ; 

exit(iy; 

if (clntjcall <g1^ 1^ xdr^int, 4num, xdr^int, tans, 
TIMEOUT) !- RPCJSUCJCESS) { 

clnt.j>error(cl, *j:avr*); 
exit(l); 

printf ("Client: nuKiber returned %d\n*, ans); 



(continued on next page ) 
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static void 
9^xviQr(rq9tPr tranpp) 

Struct sYCjpeq ♦iqstp; 
*t£ansp; 



int num; 

»wtt<S* (xx38tp-^>rqjproc) { 
cade 0: 

If (svc^seixireply^transpr xdrjvold, 0} ^ NUEL) { 
fprintf (stcte^fr, "error In null proc\n"); 
«cit (1); 

return; 

o&se It 

break; 

default: 

avcerr_noproc (transp) ; 
xetnxn; 

if (!svc_getarg5<tranisp, »drjtnt# finum)) { 
svcerrjdecode (trandp) ; 
return; 

num++; 

if (svc^sendr^ly(transpr jcdr^int, (num) NULL> { 

fprintf (atderr^ »»error in sending an»wer\n"); 
exit (1); 

||||||||||||;||;;;|| 

return; 



Note the following points: 

■ The server is not registered with rpcbind, and svc_run () is not called. 
The last parameter to svc_reg () is 0, which means that it will not regis- 
ter with rpcbind. 

■ All the RPC calls occur within the same thread of control. 
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■ It is necessary that the server be created before the client. 

■ svc_raw_create() takes no parameters. 

■ The server dispatch routine is the same as it is for normal RPC servers. 
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This section addresses areas of occasional interest to programmers using the 
lower level interfaces of the RPC package. The topics discussed are: 

if calling svc_run () is not feasible, a server 
can call the dispatcher directly 

details of the broadcast mechanism are 
described 

efficiency is gained if a series of calls can be 
batched 

two methods in common use are described 

details are provided for interfacing with the 
inetd and listener port monitors 

how programs with multiple versions are ser- 
viced 



select 0 on the server side 

broadcast RPC 

batching 

authentication 
port 

versions 



selectQ on the Server Side 

Suppose a process is processing RPC requests while performing some other 
activity. If the other activity involves periodically updating a data structure, the 
process can set an alarm signal before calling svc_run () . 

If the other activity involves waiting on a file descriptor, however, the 
svc__run ( ) call will not work. 

Below is the code for svc_run () . Note that svc_fdset is a bit mask of all 
the file descriptors that RPC is using for services. The mask can change every 
time any RPC library routine is called, because descriptors are constantly being 
opened and closed: 
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iilM^Siiiiiiiliiilil 
iiiiiiiiiiiiiiiiiiiiliiiiiil^ 

extern int errno; 

for (;;) { 

r9ac|f<j9 - 3vc^f<}3et; 

dvitch (delect (jt:ptU^si3:e<)^ i^teadfds^ 

<fd_set *)0, Tfdjet *)0, (struct tlraeval *)0)) ( 

case -X: 

If (erzno ^ EINTEiy { 
ccwtlnue; 

iliiiiiilliliiliiiiiiilii^^ 
iiiillliiiiiiiliiiliii 

* log an error: dvc run: select failed 
return; 

caae 0: 

continue; 

default: 

avc^etna^sdt ((readfdd) ; 

iiiiiiiiiiiiiiiiiiiiiiiil 

v J 

A process can bypass svc_run {) and call svc_getreqset () (the dispatcher) 
directly. Given the file descriptors of the transport endpoints associated with 
the programs being waited on, the process can have its own select () that 
waits on both the RPC file descriptors, and its own descriptors. 

Broadcast RPC 

rpcbind is a daemon that converts RPC program numbers into network 
addresses comprehensible to any transport provider, rpcbind supports broad- 
cast RPC. Here are the main differences between broadcast RPC and normal 
RPC calls: 
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■ Normal RPC expects one answer, whereas broadcast RPC expects many 
answers (one or more answer from each responding machine). 

■ Broadcast RPC can only be performed on connectionless protocols that 
support broadcasting, such as UDP. 

■ The implementation of broadcast RPC treats all unsuccessful responses as 
garbage by filtering them out. Thus, if there is a version mismatch 
between the broadcaster and a remote service, the user of broadcast RPC 
never knows. 

■ All broadcast messages are sent to rpcbind's network address. Thus, 
only services that register themselves with rpcbind are accessible via the 
broadcast RPC mechanism. 

■ The size of broadcast requests is limited to the MTU (Maximum Transfer 
Unit) of the local network. For Ethernet, the MTU is 1500 bytes. 

The following illustrates how rpc_broadcast () is used and describes its 
arguments: 



♦inolqcte <apc/cXiit .h> 
#iftclucte <xpc/xpdcfjelnt,h> 

enuitt cJiit_atat clnt_3tat; 

clntj9tat rpcjaroadcast (prognum, versnura, procnum, 
Inproc^ In^ outptoc, out^ eachreduXt* tiettype) 

Tijlotig pjfognum; /♦ pr6gram number ♦/ 

ti_^lorig -wer^imm; /* version number ♦/ 

nJLonq procnum; /* procedure number */ 

aodrprpqjt Inproc; /* xdr routine for Axqs */ 

caddrj: In; /* pointer to args */ 

xdrproej: outprOO;;! /* routine for results */ 

<!a4?|r^t out; /* pointer to results ♦/ 

x«miXtp«»ct edchJ»>sult;/* call with each result gotten */ 
dhar *nettype; /* transport type */ 



The procedure eachre suit 0 is called each time a valid result is obtained. It 
returns a boolean that specifies whether the user wants more responses. 
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booit dottft; 

done - eaohjnesuXt (resuitsp/ jradte, wjcmf) 

ptruct netbuf ^adeSr; /* Adcbr of responding maciiinje: */ 
stiMCt netcontlg *nconf ; /* Twwwport *rtiicsh ^wpcnded V 

V J 

If done is TRUE, then broadcasting stops and rpcjbroadcast () returns suc- 
cessfully. Otherwise, the routine waits for another response. The request is 
rebroadcast after a few seconds of waiting. If no responses come back, the rou- 
tine returns with RPC TIMEDOUT. 



Batching 

The RPC architecture is designed so that clients send a call message, and wait 
for servers to reply that the call succeeded. This implies that clients do not 
compute while servers are processing a call. This is inefficient if the client does 
not want or need an acknowledgement for every message sent. It is possible for 
clients to continue computing while waiting for a response, using RPC batch 
facilities. 

RPC messages can be placed in a "pipeline" of calls to a desired server; this is 
called batching. Batching assumes that: 

■ each RPC call in the pipeline requires no response from the server, and 
the server does not send a response message 

■ the pipeline of calls is transported on a reliable byte stream transport such 
as TCP/IP 

Because the server does not respond to every call, the client can generate new 
calls in parallel with the server executing previous calls. Furthermore, the 
TCP/IP implementation can buffer up many call messages, and send them to 
the server in one write 0 system call. This overlapped execution greatly 
decreases the interprocess communication overhead of the client and server 
processes, and the total elapsed time of a series of calls. 
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Because the batched calls are buffered, the client should eventually do a non- 
batched call to flush the pipeline. 

An example of batching follows. Assume a string rendering service (like a win- 
dow system) has two similar calls: one renders a string and returns void 
results, while the other renders a string and remains silent. The service (using 
the TCP/IP transport) may look like: 



f include <atdio.h> 
#includ9 <xpq/rpq^h> 

void windoiidispatclxO? 



main <) 
( 



) 



int tium; 

Rum svcjC£t6ate(vindowd[ispdtdi, WlNDOWPROGr 

WINDOWvS?S, "top**); 
if (nuin — 0) ( 

fprintf (dtderr, "can't create m RPC $^tv^t\n**): 

exit (1); 

.fprintf (std&xr, "3hould never reach this pQint\n»> ; 



void 

wi})do»Klidpatch(r<|stp/ tranisp) 

struct Bvc^req ^zqstp; 



( 



char *s *• HOLLir 

switch (J^qstp->l^qJ)roc) { 
case JJJtLPBOC: 

if (3svcjwndrepXy(tranap, xdrvoid^ 0)) 

fprintf ^Stdsrr, 'qan^t J?epiy to RPC callXn^); 

return; 
Case REKDERSmmSi 

if (TsvcjgetargsCtransp, xdr_wrapstring, &s)> { 

fprintf (stderr, "can't decode arguwentsNn*) ; 

* Teli caller an error occurred 
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break; 

* <3ode Iwns to wwder the string » 

i£ <l9vc^9en(jtreply<txan9p, xdrjroi^, NOLL)) 

fprintf (atderr^ **can't r^Xy to MO cdli\tt*>/ 

if <SdVCj90i:«riffA<tc«tuip «drwrap9tring, «9)i) ( 

fprlntf (stderr, >*<»n^t decoda azgumentgXn*'^ ; 

liiiliili 

^ Me axe silent in the face 6f p2x>tocol errors 

iiiiiiii 



break; 



default: 



* Code here to render string s, but send no reply! 
break; 

svcerrjioproc (transp) ; 
return; 



* IScM free string alXoeated decoding argumientd 

llillllllliiliiiiill 

»vcs_freearg5(transp# xdbrwr^string^ 43); 



Of course, the service could have one procedure that takes the string and a 
boolean that specifies whether the procedure should respond. 

To take advantage of batching (using the code above), the client must make RPC 
calls on a TCP-based transport. The calls must have the following attributes: 

■ the XDR routine for the result must be zero (NULL) 

■ the RPC call's timeout must be zero 



7-44 



Programmer's Guide: Networking Interfaces 



Advanced RPC Programming Techniques 



Here is an example of a client that uses batching to render a bunch of strings; 
the batching is flushed when the client gets a null string (EOF): 



fincXude <atdlo.h> 
llACludd <2p<s/ijxs.h> 
♦include "windows. 

main(argc, argv) 

int angc; 



ehar **argv? 

Struct tlflwval totiaXjtiineout; 

mm cint_^5tat c34»t^8tat; 
diauc buf [looo], *s ^ buf; 

if ((client - clnt_create(argv[l], MISDOWPROG, 
WINDOWVERS, "tc^j**)) ^ MltL) { 

clntjpcreateerror("clnt_create'') ; 
exit (X); 

total_timeoat.tvjsec - 0; 
total_tiJneout,tvttdec - 0; 
while~(»canf (ns", s) !- BaP> { 

Clnt_call (clients RENDER5TRIII3_BATCKED, 

xdrjirapatring, is, xdrjrotd, WJLL, totaljtiroeotit) ; 

/* Now flush the pipeline */ 
totalj:iJtteout.tv_see - 20; 

clnt_stat - clnt__call(cllent* NULLPROC, xdr_voldr NULL, 

xdrjvoid/ NULL, tQtal_tlmeout) ; 
if (clnt^stat RPCJ5aCCESS> { 

clntjperror (client* ''ipc"); 

exit(l); 

clntjieotroy (client) ; 
exltTo) / 



Because the server sends no message, the clients cannot be notified of any of the 
failures that may occur. 
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Batching Performance 

The following illustrates the benefits that may be gained from batching. 

The above example was completed to render all the lines in a 2000 line file. The 
rendering service did nothing but throw the lines away. 

The example was run in four configurations, with the following results: 



Configuration Time 

machine to itself, regular RPC 50 seconds 

machine to itself, batched RPC 16 seconds 

machine to another, regular RPC 52 seconds 

machine to another, batched RPC 10 seconds 



Running f scanf () on the same file only requires six seconds. These tinungs 
show the advantage of protocols that allow for overlapped execution. 

Authentication 

In the examples presented so far, the caller never identified itself to the server, 
and the server never required an ID from the caller. Some network services, 
such as a network filesystem, require stronger security than what has been 
presented so far. 

Every RPC call is subjected to a style of authentication by the RPC package on 
the server. Similarly, the RPC client package generates and sends authentication 
parameters suitable for the style of authentication in effect. The default authen- 
tication style is AUTH_NONE (none). 

Just as different transports can be used when creating RPC clients and servers, 
different forms of authentication can be associated with RPC clients. 

The authentication subsystem of the RPC package is open ended. That is, 
numerous styles of authentication are easy to support; programmers can design 
their own authentication style and easily configure the RPC package to support 
it. 
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In addition to AUTH_NONE, the RPC package already supports the following 
authentication styles: 

AUTH_SYS An authentication style based on traditional System V operating 
system process permissions authentication. 

AUTH_SHORT An alternate form of AUTH_SYS used by some servers for 
efficiency. Client programs using AUTH_SYS authentication 
should be prepared to receive AUTH_SHORT response verifiers 
from some servers. See "Authentication Protocols" in the 
"Remote Procedure Calls: Protocol Specification" chapter for 
details. 

AUTH_DES An authentication style based on DES encryption techniques. 



AUTH^NONE: The Client Side 

When a caller creates a new RPC client handle as in: 



clnt * cXnt_jCfreat©(ho8t, prognum, verswum^ nettype) 



J 



the appropriate transport instance defaults the associated authentication handle 
to be 



If the programmer creates a new style of authentication, the programmer is 
responsible for destroying it with auth_destroy (clnt->cl_auth) . This 
should always be done, to conserve memory. 
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AUTH^NONE: The Server Side 

Service implementors have a harder time dealing with authentication issues 
because the RPC package passes the service dispatch routine a request that has 
an arbitrary authentication style associated with it. Consider the fields of a 
request handle passed to a service dispatch routine: 



* An RPC Service request 
attuGt sv<jj?6<^ { 

u^lcng rqjprog; /* service program nui»toer */ 

tt^Xong txiydta^ /* service protocol vers no» */ 

u^long rqjMroc; /* (Jesired procedure mmflser */ 

Struct opaque_^auth rqjsr^; /* raw crecJentiais frcm wire */ 

caddxrj: rq^clntcred; /* credentials {read only) */ 



SVCSCPRT *rqjcprt; /* associated transport */ 



The rcLcred is mostly opaque, except for one field of interest: the style or 
flavor of authentication credentials: 



* Authentication info. Mostly opa<3ue to the prograwiaer. 

iiiiiiiiiiiiiiiiiiiiiiiiiiiiii 

struct opaque^auth { 

enum^t oajClavor; /* style of credentials */ 



caddrj; oaj^ase; /* address of more auth stuff */ 

tt^int oa^length; /* not to exceed MAX_AUTH_BYT]K */ 



The RPC package guarantees the following to the service dispatch routine: 

■ The request's revered is well formed. Thus the service implementor 
may inspect the request's rq;_cred . oa_f lavor to determine the style of 
authentication the caller used. The service implementor may also wish to 
inspect the other fields of rq^cred if the style is not one supported by 
the RPC package. 
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■ The request's rq_clntcred field is either NULL or points to a well 
formed structure that corresponds to a supported style of authentication 
credentials. Remember that only AUTH_NONE, AUTH__SYS, AUTH_SHORT 
and AUTH_DES styles are currently supported, so (currently) 
rcLclntcred could be cast only as a pointer to an authsys _parms, 
short_hand_verf , or authdes_cred structure. If rq__clntcred is 
NULL, the service implementor may wish to inspect the other (opaque) 
fields of rq^cred if the service knows about a new type of authentication 
that the RPC package does not know about. 



AUTH^SYS Authentication 

The RPC client can choose to use AUTH_SYS style authentication by setting 
clnt->cl_auth after creating the RPC client handle: 



clnt->cl^auth « aath3y5j9x<9atejd[9f ault ; 



This causes each RPC call associated with clnt to carry with it the following 
authentication credentials structure: 





liiiiiiiiiiiiiiiii 






* ADTHJSYS style credentials. 




*/ 






struct authsys^j>annd { 




xi_^long 


aup^time; 




char 


♦aufMnachnaime; 




uid__t 


a\j^juld; 




^icMt 






lljlnt 















/* credentials creation time */ 
/* host nawe idtere client is */ 
/* client's effective uid */ 
/* client's can?eait group id */ 
f* element length of au{>jgrids ^/ 
/* array of groups user is In */ 



These fields are set by authsys_create_default () by invoking the 
appropriate system calls. 
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The following shows the server for a remote procedure, RUSERPROC_n, that 
computes the number of users on the network. As a trivial demonstration of 
authentication usage, this server checks AUTH_SYS credentials and does not ser- 
vice requests from callers whose uid is 16: 



struct iV<5j&6d[ *tqstp; 



SVCXPRT ♦trviap; 

fltxuql: authsy^jparra^ *$Y3_cr8d; 

unsltfned long nus^r^; 

iiiiiiiiiiiiiiiiiiiiii^iii^ 

* lite don't cAtti iibout iuth^tiCitl<»i f<at mil pitoc 

if {tqdtp->xqj>xoc ^ NOIXPBOC) { 

If (!svG_9endxeply(transp, xdrvoid, 0)) { 

fprlntf (stderr^ "can't reply to RPC call\n»»); 



£<etixtn (1); 



3?etum; 

iliililiiiiiiiiiiiiii^ 
iiililillllll^ 

* mm get the uid 
3witch (xqi3tp->rq__cred.oa_flavor) { 
j5Y5j5red * 

(atxuct authaysjrtktjns *)tqstp->tqjiXntcx&di 

uld *• sySj2zed->ii3|>juld; 

break; 
caae adthnone: 
default; ^ 

^voerr j#eak»uth (transp) ; 

zietbSdi; 

#vitdi <r<}atp->»^£oc) { 

* make sure caller is alio**ed to call thia proc 

if (uid — m { 

svcerr_dy5teinerr(t^ah5p) ; 
return; 
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iiiiiiiiiiiiiiiiiiiiiiiiiiiii^ 

* Code ymm to oc5iBp«t# t*« nwnber of ixseirs 
^ and aaaii^ it to thet variable nusers 

it (l9vc_36Rdxei>Xy(tiran8p» wSrjBjLorHj^ (nusersH ( 

ffil:int£(dtdter, ^(Satt'lt to M>C ciillXn*); 

return (1); 

Xdtiitn; 

dvcerrjtopxoe (tranap^ ; 
zi^tuzn; 

V 

A few things should be noted here: 

■ It is customary not to check the authentication parameters associated with 
the NULLPROC (procedure number zero). 

■ The server should call svcerr_weakauth () if the authentication 
parameter's type is not suitable for the service. 

■ The service protocol itself should return statuis for access denied; in this 
example, the protocol does not have such a status, so the service primitive 
svcerr_systemerr () is called instead. 

The last point underscores the relation between the RPC authentication package 
and the services: RPC deals only with authentication and not with individual ser- 
vices' access control. The services themselves must establish access control poli- 
cies and reiflect these policies as return statuses in their protocols. 

AUTH_DES Authentication 

AUTH_DES authentication is recommended for programs that require more secu- 
rity than that offered by the AUTH_SYS style of authentication. 

AUTH_SYS authentication is easy to defeat. For example, instead of using 
authsys_create_default () , a program could call authsys_create () , 
and then change the RPC authentication handle to give itself any desired user 
ID and hostname. 
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The details of the AUTH_DES authentication protocol are complicated and are 
not explained here. See the ''Remote Procedure Calls: Protocol Specification" 
chapter for the details. 

For AUTH_DES authentication to work, the keyserv(lM) daemon must be run- 
ning on both the server and client machines. The users on these machines need 
public/secret key pairs assigned by the network administrator in the pub- 
lickey(4) database. And, they need to have deaypted their secret keys using 
the keylogin(l) conunand. 

AUTH^DES: The Client Side 

If a client wishes to use AUTH_DES authentication, it must set its authentication 
handle appropriately. Here is an example: 

f 

cX->cl aisth - atjthdes 3eccreat<9 (seirvernaine, 60^ server^ NTO.); 

V " 

The first argument is the network name or "netname" of the owner of the server 
process. Typically, server processes are root processes and their netname can be 
derived using the following call: 

.^^^ 

char servexnai«IMMaiiE!m»MEI^J; 

V J 

Here, rhostname is the hostname of the n\achine the server process is running 
on. host2netname () populates servername to contain this root process's 
netname. If the server process was run by a regular user, one could use the call 
user2netname ( ) instead. Here is an example for a server process with the 
same user ID as the client: 
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char s0tvdxna»id{MftXHB!X)IMCL^ 

V 

The last argument to both of these calls, user2netname () and 

host 2net name () , is the name of the naming domain where the server is 

located. The NULL used here means "use the local domain name." 

The second argument to authdes_seccreate {) is a lifetime for the creden- 
tial. Here it is set to sixty seconds. What that means is that the credential will 
expire 60 seconds from now. If some mischievous program tries to reuse the 
credential, the server RPC subsystem will recognize that it has expired and will 
not grant any requests. If the same mischievous program tries to reuse the 
credential within the sixty second lifetime, it will still be rejected, because the 
server RPC subsystem remembers credentials it has seen in the near past, and 
will not grant requests to duplicates. 

The third argument to authdes_seccreate () is the name of the host to syn- 
chronize with. For AUTH_DES authentication to work, the server and client 
must agree on the time. Here we pass the hostname of the server itself, so the 
client and server will both be using the same time: the server's time. The argu- 
ment can be NULL, which means "don't bother synchronizing." A program 
should pass NULL only if sure the client and server are already synchronized. 

The final argument to authdes_seccreate () is the address of a DES encryp- 
tion key to use for encrj^ting timestamps and data. If this argument is NULL, 
as it is in this example, a random key will be chosen. The client may find out 
the encryption key being used by consulting the ah_key field of the authentica- 
tion handle. 

AUTH^DES: The Server Side 

The server side is simpler than the client side. Here is the previous example 
rewritten to use the AUTH_DES style instead of AUTH_SYS: 



J 
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#incXiacte <cpc/tpc,h> 



ptruct avcj?eq *rqstp; 



stnact authdes_^crBcJ ♦DE5^cr«J; 

uidt uid; 

gidjt gid; 

int gldXen; 

gid t gidlistllOJ; 

* ine don't cafe about authentication toi: nqil proc 



if (3«}atp->rctjP>roc — DIUUPSDC) ( 
/* same as before 



* now get the uid 

switch (xqstp->xcLcred»oa^flavor) ( 
case At3TH_DES: 

DESjcred «• 

(struct authdes^cred *) 3Ki8tp->rqjclntcred; 
if <» ttettia»e2user(DES_cred->adcjeullnaine.name/ 
• fiuld, &gid, figldlen,"gidlist> > { 

fprintf (stderr/ •'unknown user: %s\n^^ 

DBSjcxed->adc_fullnanerna2n8) ; 
svoerr^systemerr(transp> ; 
return; 

i^il^iiiliiiiiliiiiiiiiiiii^ 

break; 
case AOTHJIONE: 
default: 

svcerrjieakautli (transp) ; 
t:etu£n; 

iiiiiiiiiliiliili^liiili 



iiilliiiiiiiiii;^^ 

* Ihe rest is the same as before 
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Note the use of the routine netname2user () , the inverse of 
user2netname () : it takes a network ID and converts to a local system ID. 
netname2user 0 also supplies the group IDs, not used in this example, but 
which may be useful to other programs. 



Using Port Monitors 

An RPC server can be started from port monitors such as inetd and 
listener. These port monitors listen for requests for the services, and spawn 
servers in response to those requests. The forked server process is passed the 
file descriptor 0 on which the request has been accepted. For inetd, after the 
server has serviced the request, it may exit immediately or wait a given interval 
of time for another service request to come in. 



NOTE 



For the listener, servers should exit immediately because the listener 
will always spawn a new process rather than give a request to a waiting 
server process. 



The following routine can be used to create a service: 



nconf is the netconf ig structure of the transport on which the request came in. 

Because the port monitors have already registered the service with rpcbind, 
there is no need for the service to register itself. Nevertheless, it must call 
svc__reg() : 




The netconf ig structure here is NULL. 
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NOTE 



Programmers should study rpcgen -generated server stubs to better see the 
sequence in which these routines are called. 



For connection-oriented transports, the following routine provides a lower level 
interface: 



r 



tran^p 9vcJfdjBxeatft(0r xec!V9iz0, 3and9ize> ; 



The file descriptor passed here is 0. The user may set the value of recvsize or 
sendsize to any appropriate buffer size. If they use a 0 in either case, a system 
default size will be chosen. This routine should be used by application servers 
that do not do any listening of their own, i.e., servers that simply do their job 
and return. 

Using inetd 

The format of entries in /etc/inetd. conf for RPC services is as follows: 

rpc_prog/vers socket Jype rpc/proto flags uid pathname args 

where rpcj)rog is the symbolic name of the program as it appears in rpc(4), 
vers is the version number, socket Jype is one of dgram or stream for connec- 
tionless or virtual circuit transport, respectively, proto is transport protocol, such 
as top or udp and must make sense with respect to the specified socket Jype; 
flags is one of wait or nowait, uid must exist in /etc/passwd, pathname is 
the full path name of the server daemon and args are arguments to be passed to 
the daemon when it is invoked. For example: 



For more information, see inetd. conf (4). 
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Using the listener 

We will assume here that the reader already knows the details of setting up the 
listener process and of using pmadm. The following shows how to use pmadm 
to add RPC services: 

pmadm -a -p ptnjag -s svctag -i id -v ver \ 
-m ^nlsadmin -c command -D -R progivers^ 

Here -a means to add a service, -p pmjag specifies a tag associated with the 
port monitor providing access to the service, -s sxH:tag is the server's identifying 
code, -i id is the /etc/passwd user ID assigned to service svctag, -v ver is 
the version number for the port monitor's database file and -m specifies the 
nlsadmin command for invoking the service, nlsadmin may have additional 
arguments. For example, to add version 1 of a remote program server named 
rusersd the pmadm command might be: 



# pfMdm -a -p tcp s ^tiaera root -v 4 \ 

> -tt 'nlsadnin -c yudr/dbitt/rpe.jcudferd -D -41 100002 :X' 



Here, the command is given root permissions, installed in version 4 of the 
listener database file, and is made available over TCP transports. 



Because of the complexity of the arguments and options that can foilow the 
NCrTl; pmadm -a invocation, it may be convenient to use a command script or the 
menu system to add RPC services. If you use the menu system, enter 
sysadm ports, then choose the port_services option. 

After adding a service, the listener must be reinitialized before the service 
will be available. This is accomplished by stopping, then retarting the listener, 
as follows (note that rpcbind must be running): 



# sacddm -k -p jmta^ # stop the XiBtener 

# aacadm -a »p jmta^ # start the listener 
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For more information, see the listen(lM), pmadm(lM), sacadmdM) and 
sysadm(lM) manual pages and the System Administrator's Guide. 
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This section contains examples. 

"Versions" shows how to register multiple versions of a remote procedure. 

"Connection-oriented Transports" shows a remote copy program. 

"Callback Procedures" shows how a server can be made to place a "client call" 
back to a client that calls it. 

"Memory Allocation With XDR" illustrates how this is done. 

Versions 

By convention, the first version number of program PROG is PROGVERS_ORIG 
and the most recent version is PROGVERS. 

Suppose there is a new version of the ruser program that returns an 
unsigned short rather than a long. If we name this version 
RUSERSVERS__SHORT, then a server that wants to support both versions would 
do a double register. The same server handle would be used for both of these 
registrations. 

f ^ 

if {lA^cjceqittmsp, WSS3^l^, Rt)SERSVE»SjORIG, 
nu3er, nconf)} { 

fprlntf (stctexr* "can't register ROSER ^ervlceXn**) ; 
exltd); 

\ 

if (tavcjcegttransp^ ROSERS£>RDG^ WJSERSVEJ^^SHORT, 
miser, )iconf>> { 

fpriwtf <8t<JBrr, "can't register ROSESPt serviceXn") ; 
exit(l>/ 

V J 

Both versions can be handled by the same C procedure: 
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■ ^ 

strudt svc_xoq *rqstp; 
SVCXPKP *trainsp; 

iiiiiiiiiiilliiiiiliiiii 

unsigned Iqng nuBer?; 

switch i(ia3flftp->zqjp»roq) { 

if (tsxrcjsea!)dreply<trandp,. xdr^Void, 0)) ( 

JTpirintf («tcterr. -csan't ^ply to RPC <SAll\ar\: 
t«ttxm (1); 

nBtu?;n (0); 

ISiaSEbS^^ NTH: 

* Codfe hfeKe to cottipiite th^ nt»nl»5e of us^re 

* and assign it to the variable nusers 

ttuserd2 - nuaers; 

switch (rqatp~>rq_yers) | 

case RPS&RSVS^jORIG; 

if (tsvc^aendreply(transp, aodrjii^long, 
finusefs)) ( 

fprintf (stderr^^'can't xeply to W?C caXX\n**); 

case RDSEttSVBt^jSHC^: 

if (Isvqj9endzeply(traii8p, aodrji^short, 
<lnuseird2)) { 
^rintf <stdetr,*»can't reply to RPC OallXn''); 

brealc; 







defatiit: 




sveerr jt«^>roc(transp) ; 




return; 






) 

return (0); 

\ 

V 








J 
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Connection-Oriented Transports 

Here is an example that copies a file from one system to another. The initiator 
of the RPC send call takes its standard input and sends it to the server 
receive, which prints it on standard output. This also illustrates an XDR pro- 
cedure that behaves differently on serialization than on deserialization. 



on <^Qde/ read from wire, write ontQ fp 
on encocte* ve^d frcm fp^ *irlte onto wijce 



/* 








* 


The xdj 


r routine; 


* 
















llnducle ' 


(st<iio.h> 



FILE *fp; 

Unsigned long a lie; 
char buf [BDFSIZ], *p; 

if (itdi^s->^tJ)p 5CDREREE) /* nothing to free */ 

return 1; 
while (1) { 

if (3tdrs->x__op — XDRENCJOEE) ( 

if iisize - frea<J<bufy slzeof (char) , BDFSIZ, 
fp>) 0 « £e4frot<fp)) { 

fprintf (stderr, *»<»n't fread\n«); 

xetuim (1); 

p ^ buf; 

if (!xdrjE}yte9(xc|r9( £p, {size, BQF3IZ>> 

return 0; 
if (size 0) 

return 1; 
if (»irB->X_op — XimjDECODB) { 

if <fwrite(buf, 5i2eof (char), size, 
fp) J- size) ( 

fprintf <st<terr^ »*can't fwriteXn**); 



return <i); 



1 
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Note that in the following two screens, the serializing and deserializing is done 
only by xdr_bytes () . 



♦include <8t<Jlo.h> 
llncXucJe -<n^tdb.h> 
linqlude <rp<?/rpo^h> 
linclude <»y»/80C!ket.h> 
iinttlude <sya/tim6,h> 

Int idizgc; 
char **argv; 

Int acdr__rq)<); 

if (ati^c < 2) { 

fprlntf (stderr, "usage: %s servemaiiie\n", argv£Ol>; 
exita>; 

iiiiiiiiiiiiiiiiiiiiiiiiii^ 

(callcot»(argv[l]^ RCPPROG^ RCPPROC^ BCPVERS, 
xdtjccpf stditt/ ^cdrjroia, 0) 1-0) ( 



exit(l); 



toit<0) } 



} 



callcQt* (host, prognum, procnrati, ^rsnuro, inpxoc, in, outproc, out) 
char *host/ *in/ *out; 



r 



3Cdxp(rocj: inproe^ outproc? 

enum clnt_Stat clnt^Stat; 
2^egister CLl£MT ^cli^Rt^ 
struck %i3ti0ivBl totaljiiin^cixt; 

if ((client «* clnt_cre&t^(h<:>st, pzognum^ V^rstttinic 
"circuit^v")) —""null) { 



perror(*'clntjc»eate'*) ; 
return (-1); 



total_tlm60ut.tv_sec * SO; 
total^timeout^tyjasec 0; 
clnt^atat - elntjsaXl (client, procntao^ 

inprbc, in, cAXtptOG, out, totaljiijnacut) ; 
clnt_clestroy (clients ; 
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if (clnt^ntat l-' «PCSUtX»SS> { 
xettam ((int)clnt at at); 



* The receiving rgutines 

finclude <atdiQ.h> 
♦include <rpc/rpc»h> 



int rcp^sorvlceO, xdrjrcpO; 

If (a^cjcir6ate(£pe_s6xvlti6, lx::PVl»DG, 6c&vet^4' 
"qirxMitjv") —0) ( 

eJtit(l); 

svcjomOi never rettixtta */ 

fprintf (stderr, '*svc_zun should never retuzn\n^>; 



} 



tcpj^mice(tqstp, tranap) 

register struct avcSjDeq *rqstp; 
??egiater svcxprt *tranap; 



( 



awitch <rqatp->rtLprpq) { 

caae nollproc; 

if (avd^adndtfitplyttra&ap, xdrjvoid, D> 0) ^ 
fprintf (atderr^ "err; rcp^aervice") ; 
xetiaim UV; 

if (lavqjgetargaCtransp, xdr_rcp, stdout > ) { 
avcerrjJeccde (tranap) ; 
return (1); 

if (lai^jae9:K3reply<tr«a^3p, xdcjroid, 0}} i 



(continued on next page) 
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iiiililiiilliiiiiiiiiiili;^ 

return (0); 

default: 

svcerrjioproc(t37?uwp) ; 
return (X)t 

llllilllliilllliillllll:^ 
iiiiiliiiillliiiiiilil 



















Note that on the server side no explicit action was taken after receiving the 
arguments. This is because xdr^rcp () did all the necessary dirty work 
automatically. 



Callback Procedures 

Occasionally, it is useful to have a server become a client, and make an RPC call 
back to the client process. An example is remote debugging, where the client is 
a window system program, and the server is a debugger running on the remote 
machine. Most of the time, the user clicks a mouse button at the debugging 
window, which converts this to a debugger command, and then makes an RPC 
call to the server (where the debugger is actually running), telling it to execute 
that command. However, when the debugger hits a breakpoint, the roles are 
reversed, and the debugger wants to make an rpc call to the window program, 
so that it can inform the user that a breakpoint has been reached. 

To do an RPC callback, a program number is needed to make the RPC call. 
Because this will be a dynamically generated program number, it should be in 
the transient range, 0x40000000 - OxSfffffff. In the following example, 
the routine gettransient () returns a valid program number in the transient 
range, and registers it with rpcbind. The call to rpcb_set () is a test and set 
operation, in that it indivisibly tests whether a program number has already 
been registered, and if it has not, then reserves it. 
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fiacXudte <!5tdio.h> 
f include <xpc/icptx.y£> 
lincXwte <r(etconfig*h> 

lilt ^}er«; 

9t£UGt netconfig *ncQnf ; 
struct netbuf ^addr^dd; 

iiiiiiiiiiiiiii 

static int pnog - 0*40000000; 

iftlUe (t ipcl>^aet<pj:og++* ver9# nccnf* addre33>> 

contlnud; 
return (prog - 1); 

V' J 

The following program illustrates how to use the gettransientO routine. 
The client makes an RFC call to the server, passing it a transient program 
number. Then the client waits around to receive a callback from the server at 
that program number. The server registers the program EXAMPLEPROG, so that 
it can receive the RFC call informing it of the callback program number. Then 
at some random time (on receiving an ALRM signal in tihis example), it sends a 
callback RFC call, using the program number it received earlier. 
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*/ 

#incXude <dtdio.h> 
llnclude <rpc/rpc.h> 
#incJ.Tide <netconfig,h> 
lineXtide ^exarople.h*' 

xnaln(argc, argv) 



{ 



char **a3pgv; 

SVCXPRT *xprt; 
itzuet hetconflg *n<;onf; 
Int prognum; 
entutt eXnt^atat stat; 

if (atge 3) { 

fprintf (stderr , "usage: clnt host transport Vn") ; 
exit (IK- 

ncoinf » getnetccnf igent (axgvt2] ) ; 
if (nconf — TO1> { 

fptrlntf (stderr, "unknown transport\n") ; 
exit (ly; 

3cprt » svGjtlijcx^ate <BPCJMSIYFD, nconf, 

(Struct t_bind *>NTO^ 0, 0); 
if (;^rt — ' (SVCDCPRT *>NOIX) { 

fprintf (stderr, "could not create server handle\n^>; 
exit (1); 

prognum » gettransient(l, nconf, ixprt->xp_ltaddr) ; 
fprintf (stderr, *»cXi^t gets pro^pium %d\n*, prc>gnu»); 
if (svCjceg (^rt, prognum, 1, callback, HULL) 
( 

f printf (stderr, ♦*could not register servlceXn*) ; 
exit(l>; 

|:;|||||||||||||||;^^ 

Stat * rpc_call(argvU). EXMffi>IEPBDG, EXWMPLEVERS, 
EXAIffLEPI^JiaLLBftCK, xdr_int^ ^prognum, xdr_void, 
NOtX, NOXX); 
if (Stat RPC_StXXESS) { 
clnt_permo (stat) ; 
exit(X); 

svc_run() ; 

(continued on next page ) 
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«xlta>; 

iillllllllllllllllll;^ 

qalll>ftck<z^tp, transp) 

i?egiarter struct svc^req *rq5tp; 
register SvC!XS>At ^transp; 

iiiliiiiiiiiiiiiiiiiiiiiiii^^ 

witdt (tq$tp-^>rc(j)roc) \ 
case Q: 

it (!3vc_S6ndE<8ply<tapwi»p, 5Kjir^void> 0)) { 
return <1>; 

^iiiiiiiiiliiiiiii^iiiii^ 

refttkzn (0); 

case 1; 

if t'svcjgetargs (transp, xdr^void, 0)) X 
svcexxrjctecode (transp) ; 
return (1); 

fprlntf (stderr, "client ^ot callback\n") ; 
it ( I svc^sendr^ly (transp^ xsdr_voi<J/ 0>) { 

f printf (stderr, **err: exan^l^rog**); 

retuzn {1>; 

;;|;||||||||||^ 

letum (0) ; 

return {2)t 

J 

This example shows how svc_tli_create () can be used when it is necessary 
to explicitly chose the program number by calling rpcb_set ( ) until it 
succeeds. (Here it was not required that a service be registered on a given tran- 
sport, and the example could simply have used a "generic" network type.) 
After creating the handle, svc_reg() is called (with the last parameter given as 
NULL) to register the dispatch function with the dispatcher. Once the server 
side is ready, it then notifies the actual server of its dynamic program number 
with rpc_call () . On success it then waits for requests from the remote 
server. 

In the following example, the server makes an RFC call to the chent on an 
ALARM signal, but only if the client has passed the program number to the 
server. This server example illustrates the simplicity of the code when one is 
using rpc_reg () . 



Remote Procedure Call Programming Guide 



7-67 



Advanced Examples 



iiiiiiiiliiiiiiiiiiiiiiiiiii 

lincXttde <!»tdio.h> 
llnqliKfe <rpc/rpa.h> 

char *^ti)^toigO; 
char "^hostname; 

Int ptkvm^ /* program nuwiber for callback routin^t ♦/ 



main 
{ 



} 



if (arcrc !•* 2) { 

f print (atdarr^ »*uj9ag^i server hostttaweXn*) ; 
exit a>; 

hostname ^ argvtXJr 

rpcj»g (EXAMPLEPRQGr EXAMPLBVEI^, EXfiHPIEPRCCjIIALZBACK, 

getnewpxog/ xdr_int, «Jrjwoicl, NOLL); 
signal (SIGRLRM, dOCaUbadcT; 
alam(lO) ; 
svcjwnO? 

f printf (stderTr ''fiJrrort sv<ijnHi shouldn't returnXn"); 



char * 

getnewprog(pnwnp> 

char i'pmtp} 



pnm *(int *)pamp^ 
return !4t)tX; 



docallback (} 
i 



int ana; 
if (pnum 

ans •* rpcjcall (hostname, pnum, 1, 1, xdrvqid, 0, 
«3r_volcl# 0* NULL); 



- 0) { 
alazm (10); 
retuni; 



(continued on next page) 
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if (ana W?C_SOCCESS) { 

f^rlntf (stdarr, •»semir: 
clntjpevxno (an»> ; 



Memory Allocation with XDR 

XDR routines not only do input and output, they also do memory allocation. 

The second parameter of xdr_array ( ) is a pointer to an array, rather than the 
array itself. 



NOTE 



This is true for most XDR routines. The indirection is necessary because 
these routines often allocate memory. 



If it is NULL, then xdr_array () allocates space for the array and returns a 
pointer to it, putting the size of the array in the third argument. As an exam- 
ple, consider the following XDR routine xdr__chararrl () , which deals with a 
fixed array of bytes with length SIZE: 



xdrjchararrl (xdrsp* chararr) 



{ 



char *p; 
int len; 

p * chararr; 
len - SIZE; 



x^tuxn (xdrJ>yteB<xdrdp« «p, il&n, SXZB))} 
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If space has already been allocated in chararr, it can be called from a server 
like this: 



To have XDR to do the allocation, this routine must be rewritten in the follow- 
ing way: 



char ♦*chararxp; 
int len; 
len « SIZE; 



Then the RFC call might look like this: 



qhar *arrptr; 
arzptr ^ iKtLL; 

9vc_g[atar95 (traxiap, xdr_chararr^, fiarxptr) ; 
/* 

Use the result hete 



Note that, after being used, the character array should normally be freed with 
svc_f reeargs ( ) . svc_freeargs () will not attempt to free any memory if 
the variable indicating it is NULL. For example, in the routine 
xdr_finalexample () , given earlier, if finalp~>string were NULL, then it 
would not be freed. The same is true for f inalp->simplep. 
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To summarize: 

■ Each XDR routine is responsible for serializing, deserializing, and freeing 
memory. 

■ When an XDR routine is called from rpc_call () , the serializing part is 
used. 

■ When called from svc_getargs () , tiie deserializer is used. 

■ When called from svc_f reeargs () , tiie memory deallocator is used. 

When building simple programs like those given as examples in this section, a 
programmer does not have to worry about the three modes. 
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Introduction to XDR 



XDR is a standard for the description and encoding of data. The XDR protocol 
is useful for transferring data between different computer architectures and has 
been used to communicate data between such diverse machines as the 3B2, Sun 
Workstation, VAX, IBM-PC, and Cray. XDR fits into the ISO presentation layer 
and is roughly analogous in purpose to X.409, ISO Abstract Sjmtax Notation. 
The major difference between the two is that XDR uses implicit typing, while 
X.409 uses explicit typing. 

XDR uses a language to describe data formats and can only be used to describe 
data; it is not a programming language. This language makes it possible to 
describe intricate data formats in a concise manner. The XDR language is simi- 
lar to the C language. Protocols such as RPC (Remote Procedure Call) and the 
NFS (Network File System) use XDR to describe the format of their data. 

The XDR standard makes the following assumption: that bytes (or octets) are 
portable, where a byte is defined to be 8 bits of data. 

Basic Block Size 

The representation of all items requires a multiple of four bytes (or 32 bits) of 
data. The bytes are numbered 0 through n-1. The bytes are read or written to 
some byte stream such that byte m always precedes byte m+l. The n bytes are 
followed by enough (0 to 3) residual zero bytes, r, to make the total byte count 
a multiple of four. 

Choosing the XDR block size requires a tradeoff. Choosing a small size such as 
two makes the encoded data small, but causes alignment problems for machines 
that are not aligned on these boundaries. A large size such as eight means the 
data will be aligned on virtually every machine, but causes the encoded data to 
grow too large. Four was chosen as a compromise. Four is big enough to sup- 
port most architectures efficiently, except for rare machines such as the eight- 
byte aligned Cray. Four is also small enough to keep the encoded data res- 
tricted to a reasonable size. 

The same data should encode into the same thing on all machines, so that 
encoded data can be significantly compared or checksummed. Forcing the pad- 
ded bytes to be zero ensures this. 
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This chapter uses graphic box notation for illustration and comparison. In most 
illustrations, each box (delimited by a plus sign at the 4 corners and vertical 
bars and dashes) depicts a byte. Ellipses (...) between boxes show zero or 
more additional bytes where required: 

A Block 

+ H +. . .+ + H. . .+ + 

I byte 0 I byte 1 | . . . Ibyte n-1 1 0 | . . . I 0 I 
+ + ^ ^+ + , 4. 

|< bytes >|< r bytes ^>| 

|< n+r (where (n+r) nod 4 » 0)> ^>| 



Organization of Technical Information 

The "XDR Data Type Declarations" section describes each atomic data type that 
can be represented using XDR 

"Other XDR Declarations" describe constants, type definitions, and optional 
data (an alternate way to express certain kinds of unions). 

'The XDR Language Specification" section provides a formal definition of the 
XDR language. 

"An Example of an XDR Data Description" shows how XDR might be used to 
describe a file. 
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Each of the sections that follow: 

■ describe a data type defined in the XDR standard 

■ show how that data type is declared in the language 

■ include a graphic illustration of the encoding 

For each data type in the language we show a general paradigm declaration. 
Note that angle brackets (< and >) denote variable length sequences of data and 
square brackets ( [ and ] ) denote fixed-length sequences of data, n, m and r 
denote integers. For the full language specification and more formal definitions 
of terms such as identifier and declaration, refer to "The XDR Language 
Specification", below. 

For some data types, more specific examples are included. A more extensive 
example of a data description is in the section "An Example of XDR Data 
Representation". 

Integer 

Description 

An XDR signed integer is a 32-bit datum that encodes an integer in the range [- 
2147483648,2147483647]. The integer is represented in two's complement nota- 
tion; the most and least significant bytes are 0 and 3, respectively. 

Declaration 

Integers are declared as follows: 
int identifier; 
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Encoding 

Integer 



(MSB) (LSB) 

+ + 1- + + 

Ibyte 0 Ibyte 1 Ibyte 2 Ibyte 3 | 

+ + h + + 

< 32 bits > 



Unsigned Integer 

Description 

An XDR unsigned integer is a 32-bit datum that encodes a nonnegative integer 
in the range [0,429496^95]. The integer is represented by an unsigned binary 
number whose most and least significant bytes are 0 and 3, respectively. 

Deciaration 

An unsigned integer is declared as follows: 
unsigned int identifier; 

Encoding 

Unsigned Integer 



(MSB) (LSB) 

+ + h + + 

Ibyte 0 Ibyte 1 Ibyte 2 Ibyte 3 | 

+ + H + + 

< 32 bits > 
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Enumeration 
Description 

Enumerations have the same representation as signed integers and are handy 
for describing subsets of the integers. 

Declaration 

Enumerated data is declared as follows: 

enum { name-identifier = constant, ... } identifier; 

For example, an enumerated type could represent the three colors red, yellow, 
and blue as follows: 

enum { RED « 2, YELLOW « 3, BLUE « 5 } colors; 

It is an error to assign to an enum an integer that has not been assigned in the 
enum declaration. 

Encoding 

See "Integer," above. 

Boolean 

Description 

Booleans are important enough and occur frequently enough to warrant their 
own explicit type in the standard. Booleans are integers of value 0 or 1. 

Declaration 

Booleans are declared as follows: 

bool identifier; 
This is equivalent to: 

enum { FALSE « 0, TRUE = 1 } identifier; 
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Encoding 

See 'Integer/' above. 

Hyper Integer and Unsigned Hyper Integer 
Description 

The standard also defines 64-bit (8-byte) numbers called hyper int and 
unsigned hyper int whose representations are the obvious extensions of 
integer and unsigned integer, defined above. They are represented in two's 
complement notation; the most and least significant bytes are 0 and 7, respec- 
tively. 

Declaration 

Hyper integers are declared as follows: 
hyper int identifier; 

unsigned hyper int identifier; 

Encoding 

Hyper Integer 

(MSB) (LSB) 

+ + 1- + + 1- +- + 1- 

ibyte 0 Ibyte 1 Ibyte 2 Ibyte 3 Ibyte 4 Ibyte 5 ibyte 6 Ibyte 7 | 
+ 1. + + 1. + + ^ 

< g4 bitg > 
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Floating-point 
Description 

The standard defines the floating-point data type float (32 bits or 4 bytes). 
The encoding used is the IEEE standard for normalized single-precision 
floating-point numbers [1]. The following three fields describe the single- 
precision floating-point number: 

S: The sign of the number. Values 0 and 1 represent positive and negative, 
respectively. One bit. 

E: The exponent of the number, base 2. Eight bits are devoted to this field. 
The exponent is biased by 127. 

F: The fractional part of the number's mantissa, base 2. 23 bits are devoted 
to this field. 

Therefore, the floating-point number is described by: 
(^1)**S * 2**(E-Bias) * l.F 

Declaration 

Single-precision floating-point data is declared as follows: 
float identifier; 

Encoding 

Single-Precision Floating Point 

+ + + + + 

Ibyte 0 Ibyte 1 Ibyte 2 Ibyte 3 | 
SI E I F i 

+ + ■' + + h 

1|<- 8 ->|<— 23 bits >| 

<— — 32 bits > 

Just as the most and least significant bytes of an integer are 0 and 3, the most 
and least significant bits of a single-precision floating-point number are 0 and 
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31. The beginning bit (and most significant bit) offsets of S, E, and F are 0, 1, 
and 9, respectively. 



These offsets refer to the logical positions of the bits, not to their physical 
locations (which vary frbm medium to medium). 



The IEEE specifications should be consulted about the encoding for signed zero, 
signed infinity (overflow), and denormalized numbers (underflow) [1]. Accord- 
ing to IEEE specifications, the NaN (not a nuniber) is system dependent and 
should not be used externally. 



Double-Precision Floating-point 
Description 

The standard defines the encoding for the double-precision floating-point data 
type double (64 bits or 8 bytes). The encoding used is the IEEE standard for 
normalized double-precision floating-point numbers [1]. The standard encodes 
the following three fields, which describe the double-precision floating-point 
number: 

S: The sign of the number. Values 0 and 1 represent positive and negative, 
respectively. One bit. 

E: The exponent of the number, base 2. 11 bits are devoted to this field. 
The exponent is biased by 1023. 

F: The fractional part of the number's mantissa, base 2. 52 bits are devoted 
to this field. 

Therefore, the floating-point number is described by: 
(-1)**S * 2**(E-Bias) * l.F 
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Declaration 

double identifier; 



Encoding 

Double-Precision Floating Point 



+ + + + + h + + + 

Ibyte Olbyte llbyte 2|byte 3|byte 4 (byte 5|byte 6ibyte 71 
SI E i F I 

+ + + H + H + + + 

1 1 <~11~> I < 52 bits > I 

< 64 bits > 

Just as the most and least significant bytes of an integer are 0 and 3, the most 
and least significant bits of a double-precision floating- point number are 0 and 
63. The beginning bit (and most significant bit) offsets of S, E , and F are 0, 1, 
and 12, respectively. 



NOTE 



These offsets refer to the logical positions of the bits, not to their physical 
locations (which vary from medium to medium). 



The IEEE specifications should be consulted about the encoding for signed zero, 
signed infinity (overflow), and denormalized numbers (underflow) [1]. Accord- 
ing to IEEE specifications, the NaN (not a number) is system dependent and 
should not be used externally. 



Fixed-length Opaque Data 
Description 

At times, fixed-length uninterpreted data needs to be passed among machines. 
This data is called opaque. 
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Declaration 

opaque data is declared as follows: 

opaque identifier [n] ; 

where the constant n is the (static) number of bytes necessary to contain the 
opaque data. 

Encoding 

The n bytes are followed by enough (0 to 3) residual zero b5^s, r, to make the 
total byte count of the opaque object a multiple of four. 

Fixed-Length Opaque 

0 1 

— . — ^ .|. + , .4. + 

1 byte 0 I byte 1 I . . . Ibyte n-1 1 0 | . . . I 0 | 
^^^^ , ^ + J., , ,4. 4. 

|< -n bytes >|< r bytes >| 

l< »»n+r (where (n+r) mod 4 = 0) >| 



Variable-length Opaque Data 
Description 

The standard also provides for variable-length (counted) opaque data, defined 
as a sequence of n (numbered 0 through n-1) arbitrary bytes to be the number 
n encoded as an unsigned integer (as described below), and followed by the n 
bytes of the sequence. 

Byte b of the sequence always precedes byte b+1 of the sequence, and byte 0 of 
the sequence always follows the sequence's length (count). The n bytes are fol- 
lowed by enough (0 to 3) residual zero bytes, r, to make the total byte count a 
multiple of four. 
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Declaration 

Variable-length opaque data is declared in the following way: 
opaque identifier<m>; 

or 

opaque identifiero; 

The constant m denotes an upper bound of the number of bytes that the 
sequence may contain. If m is not specified, as in the second declaration, it is 
assumed to be (2**32) - 1, the maximum length. For example, a filing proto- 
col may state that the maximum data transfer size is 8192 bj^es, as follows: 

opaque £iledata<8192>; 



Encoding 

Variable-Length Opaque 

0 1 2 3 4 5 ... 

+ + + + + + +. . .+ + +. . .+ + 

1 length n jbyteO Ibytel | . . . | n-1 I 0 | . . . | 0 | 

+ + + + + + +. . .H + +. . .+ + 

|< 4 bytes ^>|< ^-n bytes >|< r bytes >| 

|< n+r (where (n+r) mod 4 « 0) >| 

It is an error to encode a length greater than the maximum described in the 
specification. 



String 
Description 

The standard defines a string of n (numbered 0 through n-1) ASCII bytes to be 
the number n encoded as an unsigned integer (as described above), and fol- 
lowed by the n bytes of the string. Byte b of the string always precedes byte 
b+1 of the string, and byte 0 of the string always follows the string's length. 
The n bytes are followed by enough (0 to 3) residual zero bytes, r, to make the 
total byte count a multiple of four. 
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Declaration 

Counted byte strings are declared as follows: 
string object<m>; 

or 

string objectO; 

The constant tn denotes an upper bound of the number of bytes that a string 
may contain. If tn is not specified, as in the second declaration, it is assumed to 
be (2**32) - 1, the maximum length. The constant m would normally be 
found in a protocol specification. For example, a filing protocol may state that a 
file name can be no longer than 255 bytes, as follows: 

string £ilenanie<255>; 



Encoding 

String 

0 1 2 3 4 5 ... 

+ H H + + + +. . .+ 1- 1-. . .+ + 

1 length n |byteO|bytel| . . . I n-1 | 0 |...| 0 I 

+ + + + + + +. . .+ H . .+ + 

|< 4 bytes >|< bytes >|< r bytes >| 

|< ^n+r (where (n+r) rood 4 - 0) >| 



It is an error to encode a length greater than the maximum described in the 
specification. 



Fixed-length Array 
Description 

Fixed-length arrays of elements numbered 0 through n-1 are encoded by indivi- 
dually encoding the elements of the array in their natural order, 0 through n-1. 
Each element's size is a multiple of four bytes. Though all elements are of the 
same t3^e, the elements may have different sizes. For example, in a fixed- 
length array of strings, all elements are of type string, yet each element will 
vary in its length. 
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Declaration 

Declarations for fixed-length arrays of homogeneous elements are in the follow- 
ing form: 

type-name identifier [n]; 
Fixed-Length Array 

I element 0 | element 1 i . . . I element n-1 i 
|< ^n elements >| 



Variable-length Array 
Description 

Counted arrays provide the ability to encode variable-length arrays of homo- 
geneous elements. The array is encoded as the element count n (an unsigned 
integer) followed by the encoding of each of the arra/s elements, starting with 
element 0 and progressing through element n~l. 

Declaration 

The declaration for variable-length arrays follows this form: 
type-name identifier<m>; 

or 

type-name identifiero; 

The constant m specifies the maximum acceptable element count of an array. 
Note that if m is not specified, as is the case in the second declaration format 
above, it is assumed to be (2**32) ^ 1. 
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Encoding 

Counted Array 

0 12 3 

+ — H + — + — + — + — + — + — + — H + — + — +. . .+ — + h — + K 

1 n i element 0 | element 1 I ... I element n-1 1 

+ — H + — H + — H + — H + — H + — + — +. . .+— + — h — + — H 

|<-4 bytes->|< ^n elements >| 

It is an error to encode a value of n that is greater than the maximum described 
in the specification. 

Structure 
Description 

The components of the structure are encoded in the order of their declaration in 
the structure. Each component's size is a multiple of four bytes, though the 
components may be different sizes. 

Deciaratidn 

Structures are declared as follows: 

struct { 

component-declaration-A ; 
component'declaration-B ; 

} identifier; 

Encoding 

Structure 

+ + h. . . 

I conponent A | conponent B | . . . 
+ + h. . . 
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Discriminated Union 
Description 

A discriminated union is a type composed of a discriminant followed by a type 
selected from a set of prearranged types according to the value of the discrim- 
inant. The type of discriminant is eititer int, unsigned int, or an enumerated 
type, such as bool. The component types are called arms of the union, and are 
preceded by the value of the discriminant which implies their encoding. 

Declaration 

Discriminated unions are declared as follows: 

union switch {discrimimnt'declaration) { 
case discriminant-value- A: 

arm-declaration-A ; 
case dbcriminant-value-B : 

arm-declaration-B ; 

default : 

default-declaration; 

} identifier; 

Each case keyword is followed by a legal value of the discriminant. The 
default arm is optional. If it is not specified, then a valid encoding of the union 
cannot take on unspecified discriminant values. The size of the implied arm is 
always a multiple of four bytes. 

Encoding 

The discriminated union is encoded as its discriminant followed by the encoding 
of the implied arm. 

Discriminated Union 

0 12 3 

+ — — + — + — + — + — + — ^ — + 

1 discriminant | inplied am | 

+ H + + H — + + + 

|< 4 bytes >| 
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Void 

Description 

An XDR void is a 0-byte quantity. Voids are useful for describing operations 
that take no data as input or no data as output. They are also useful in unions, 
where some arms may contain data and others do not. 

Declaration 

The declaration is simply as follows: 
void; 



Encoding 

Voids are illustrated as follows: 

++ 

II 

++ 

-X- 0 b5rtes 
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Constant 

The declaration for a constant follows this form: 

const name-identifier - «; 

const is used to define a symbolic name for a constant; it does not declare any 
data. The symbolic constant may be used anywhere a regular constant may be 
used. 

The following example defines a S5mibolic constant DOZEN, equal to 12. 
const DOZEN «• 12; 



typedef 

typedef does not declare any data either, but serves to define new identifiers 
for declaring data. The syntax is: 

typedef declaration; 

The new type name is actually the variable name in the declaration part of the 

typedef. 

The following example defines a new type called eggbox using an existing type 
called egg and the symbolic constant DOZEN: 

typedef egg eggbox [DOZEN] ; 

Variables declared using the new type name have the same type as the new 
type name would have in the typedef, if it was considered a variable. For 
example, the following two declarations are equivalent in declaring the variable 
fresheggs: 

eggbox fresheggs; 

egg fresheggs [DOZEN] ; 

When a typedef involves a struct, enum, or union definition, there is another 
(preferred) syntax that may be used to define the same type. In general, a 
typedef of the following form: 

typedef «struct, union, or enum definition» identifier; 
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may be converted to the alternative form by removing the typedef part and 
placing the identifier after the struct, enum, or union keyword, instead of at 
the end. For example, here are the two ways to define the type bool: 

typedef eram { /* using typedef */ 
FMiSE = 0, 
TRUE » 1 

} bool; 

enum bool { /* preferred alternative */ 

FALSE » 0, 
TRUE » 1 

); 

This syntax is preferred because one does not have to go to the end of a declara- 
tion to learn the name of the new type. 



Optional-data 

Optional-data is a form of union. Because it occurs frequently, it has been 
given its own declaration syntax. It is declared as follows: 

type-name *idenHfier; 

This is equivalent to the following union: 

union switch (bool qpted) { 
case TRUE: 

type-name element; 
case FALSE: 
void; 

} identifier; 

It is also equivalent to the following variable-length array declaration, because 
the boolean opted can be interpreted as the length of the array: 

type-name identifier<l>; 
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Optional-data is useful for describing recursive data-structures such as linked- 
lists and trees. For example, the following defines a type stringlist that 
encodes lists of arbitrary length strings: 

struct *stringlist { 
string itemO; 
stringlist next; 

>; 

It could have been equivalently declared as the following union: 

union stringlist switch (bool opted) { 
case TRUE: 

struct { 

string itemO; 
stringlist next; 
} element; 
case FALSE: 
void; 

); 

or as a variable-length array: 

struct stringlist<l> { 
string itemO; 
stringlist next; 

}; 

Both of these declarations obscure the intention of the stringlist type, so the 
optional-data declaration is preferred over both of them. The optional-data type 
also has a close correlation to how recursive data structures are represented in 
high-level languages such as Pascal or C by use of pointers. The syntax is the 
same as that of the C language for pointers. 
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Notatlonal Conventions 

This specification uses a modified Backus-Naur Form notation for describing the 
XDR language. Here is a brief description of the notation: 

1. The characters \ ,(,), [, ], and * are special. 

2. Terminal sjmibols are strings of any characters in a font. 

3. Non-terminal symbols are strings of non-special italic characters. 

4. Alternative items are separated by a vertical bar ( | ). 

5. Optional items are enclosed in brackets. 

6. Items are grouped together by enclosing them in parentheses. 

7. A * following an item means 0 or more occurrences of the item. 

For example, consider the following pattern: 

a very (, very)* fcold andj rainy (day | night) 

An infinite number of strings match this pattern. A few of them are: 

a very rainy day 

a very, very rainy day 

a very cold and rainy day 

a very, very, very cold and rainy night 



Lexical Notes 

1. Comments begin with /* and end with */. 

2. White space serves to separate items and is otherwise ignored. 

3. An identifier is a letter followed by an optional sequence of letters, digits 
or underbars (_). The case of identifiers is not ignored. 

4. A constant is a sequence of one or more decimal digits, optionally pre- 
ceded by a minus-sign (-). 
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Syntax Information 

declaration: 

type-specifier identifier 
I type-specifier identifier [ value ] 
I type-specifier identifier < I value ] > 
I opaque identifier [ value ] 
I opaque identifier < [ value 1 > 
I string identifier < [ value ] > 
I type-specifier * identifier 
I void 

value: 

constant 
I identifier 

type-specifier: 

I unsigned ] int 
I I unsigned J hyper 
I float 
I double 
I bool 

I enum-type-spec 
I struct-type-spec 
I union-type-spec 
I identifier 

enum-type-spec: 

enum enum-body 

enum-body: 
{ 

( identifier « value ) 
( r identifier - value )* 
) 

struct-type-spec: 

struct struct-body 
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struct'body: 
{ 

( declaration ; ) 
( declaration ; 
) 

union-type-spec: 

union union-body 

union-body: 

switch ( declaration ) { 
( case value : declaration / ) 
( case value : declaration ; )* 
I default : declaration ; ] 
} 

constant-def: 

const identifier = constant ; 

type-def: 

typedef declaration ; 
I enum identifier enum-body ; 
I struct identifier struct-body ; 
I union identifier union-body ; 

definition: 

type-def 

I constant-def 

specification: 

definition * 
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Syntax Notes 

1 . The following are keywords and cannot be used as identifiers: 



bool 



const 

default 

double 



enum int struct union 

float opaque switch unsigned 
hyper string typedef void 



case 
char 



2. Only unsigned constants may be used as size specifications for arrays. If 
an identifier is used, it must have been declared previously as an 
unsigned constant in a const definition. 

3. Constant and tj^e identifiers within the scope of a specification are in the 
same name space and must be declared uniquely within this scope. 

4. Similarly, variable names must be unique within the scope of struct and 
union declarations. Nested struct and union declarations create new 



5. The discriminant of a union must be of a type that evaluates to an 
integer. That is, int, unsigned int, bool, an enum type or any 
typedefed type that evaluates to one of these. Also, the case values must 
be legal discriminant values. Finally, a case value may not be specified 
more than once within the scope of a union declaration. 
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An Example of an XDR Data Description 



Here is a short XDR data description of a thing called a file, which might be 
used to transfer files from one machine to another: 



const MMOPraiPWW * $5535; /* tmt- Jmim ^ » */ 



/* ujnpes of files; V 

^um f Unkind ^ 

TEXT w 0^ 



/* asdt dat* */ 
/♦ tikW data */ 
/♦ essecatabXe */ 



/* ttO extra Infonnation */ 
/* data cjjeator */ 



/* Pile infonnatlw* per kind of file; */ 

union f iletype switch (filekind kindji { 
i*ase TEXT: 

void,' 
case DATA; 

^tXiXkQ C»:eatOX<MAXMAMBLEH>; 
case EXECi 

string lnterpmoiSMA>ttiAMEXEil>; /* progtsam interpreter */ 

/* A c<xpl4St^ file: V 

struct file { 

string filendme<MAXiJ»MEtJEN>; /* name of file */ 

f iletype type; /* info aboat file */ 

String owner<MAX(7SERNaNES>; /* ouner' of file */ 
Opaqae data<»0(Flt£t£3£>; file data */ 



Suppose now that there is a user named john who wants to store his lisp pro- 
gram sillyprog that contains just the data (quit) . His file would be 
encoded as follows: 
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Offset 


Hex Bytes 




ASCII 


Description 


0 


00 


00 


00 


09 




Length of filename = 9 


4 


73 


69 


6c 


6c 


sill 


Filename characters 


8 


79 


70 


72 


6f 


ypro 


... and more characters ... 


12 


67 


00 


00 


00 


g. . . 


... and 3 zero-bytes of fill 


16 


00 


00 


00 


02 




Filekind is EXEC = 2 


20 


00 


00 


00 


04 




Length of interpretor = 4 


24 


6c 


69 


73 


70 


lisp 


Interpretor characters 


28 


00 


00 


00 


04 




Length of owner = 4 


32 


6a 


6f 


68 


6e 


john 


Owner characters 


36 


00 


00 


00 


06 




Length of file data = 6 


40 


28 


71 


75 


69 


(qui 


File data bytes ... 


44 


74 


29 


00 


00 


t) .. 


... and 2 zero-bytes of fill 
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This chapter specifies a message protocol used in implementing the Remote Pro- 
cedure Call (RFC) package. (The message protocol is specified with the External 
Data Representation (XDR) language. This chapter assumes the reader is fami- 
liar with XDR. See the "External Data Representation Standard: Protocol 
Specification" chapter for details.) 

Terminology 

This chapter discusses servers, services, programs, procedures, clients, and ver- 
sions. 

A server is a process that provides remote services to clients. 

A network service is a collection of one or more remote programs. 

A remote program implements one or more remote procedures; the procedures, 
their parameters, and results are documented in the specific program's protocol 
specification (see the "rpcbind Protocol" below, for an example). 

Network clients are processes that make remote procedure calls to servers. A 
server may support more than one version of a remote program to be forward 
compatible with changing protocols. 

As an example of how these terms are used, consider a network file service 
composed of two programs. One program may deal with high-level applica- 
tions such as file system access control and locking. The other may deal with 
low-level file lO and have procedures like "read" and "write." A client machine 
of the network file service would call the procedures associated with the two 
programs of the service on behalf of some user on the client machine. 

General Attributes of the Protocol 
The RPC Model 

The remote procedure call model is similar to the local procedure call model. In 
the local case, the caller places arguments to a procedure in some well-specified 
location. It then transfers control to the procedure, and eventually gains back 
control. At that point, the results of the procedure are extracted from a well- 
specified location, and the caller continues execution. 
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The remote procedure call is similar, in that one thread of control logically 
winds through two processes. One is the caller's process, the other is a server's 
process. Conceptually, the caller process sends a call message to the server pro- 
cess and waits (blocks) for a reply message. The call message contains the 
procedure's parameters, among other things. The reply message contains the 
procedure's results, among other things. Once the reply message is received, 
the results of the procedure are extracted, and the caller's execution is resumed. 

On the server side, a process is dormant awaiting the arrival of a call message. 
When one arrives, the server process extracts the procedure's parameters, com- 
putes the results, sends a reply message, and then awaits the next call message. 

Note that in this description, only one of the two processes is active at any 
given time. However, this need not be the case. The RPC protocol makes no 
restrictions on the concurrency model implemented. For example, an imple- 
mentation may choose to have RPC calls be asynchronous, so that the client 
may do useful work while waiting for the reply from the server. Another possi- 
bility is to have the server create a task to process an incoming request, so that 
the server can be free to receive other requests. 

Transports and Semantics 

The RPC protocol is independent of transport protocols. That is, RPC does not 
care how a message is passed from one process to another. The protocol deals 
only with specification and interpretation of messages. 

It is important to point out that RPC does not attempt to ensure transport relia- 
bility. In this regard, the application must be aware of the type of transport 
protocol underneath RPC. If the RPC service knows it is running on top of a 
reliable transport such as TCP/IP, then most of the work is already done for it. 
On the other hand, if RPC is running on top of an unreliable transport such as 
UDP/IP, the service must devise its own retransmission and time-out policy. 
RPC does not provide this service. 

Because of transport independence, the RPC protocol does not attach specific 
semantics to the remote procedures or their execution. Semantics can be 
inferred from (but should be explicitly specified by) the underlying transport 
protocol. For example, consider RPC running on top of an unreliable transport 
such as UDP/IP. If an application retransmits RPC messages after short time- 
outs, the only thing it can infer if it receives no reply is that the procedure was 
executed zero or more times. If it does receive a reply, then it can infer that the 
procedure was executed at least once. 
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A server may wish to remember previously granted requests from a client and 
not regrant them to insure some degree of execute-at-most-once semantics. A 
server can do this by taking advantage of the transaction ID that is packaged 
with every RFC request. The main use of this transaction ID is by the RFC 
client for matching replies to requests. However, a client application may 
choose to reuse its previous transaction ID when retransmitting a request. The 
server application, knowing this fact, may choose to remember this ID after 
granting a request and not regrant requests with the same ID. The server is not 
allowed to examine this ID in any other way except as a test for equality. 

On the other hand, if using a reliable transport such as TCP/IP, the application 
can infer from a reply message that the procedure was executed exactly once, 
but if it receives no reply message, it cannot assume the remote procedure was 
not executed. Note that even if a connection-oriented protocol like TCP is used, 
an application still needs time-outs and reconnection to handle server crashes. 

Binding and Rendezvous Independence 

The act of binding a client to a service is not part of the remote procedure call 
specification. This important and necessary function is left up to some higher- 
level software. (The software may use RPC itself; see the "rpcbind Protocol" 
section, below.) 

Implementors should think of the RPC protocol as the jump-subroutine instruc- 
tion ("JSR") of a network; the loader (binder) makes JSR useful, and the loader 
itself uses JSR to accomplish its task. Likewise, the network makes RPC useful, 
using RPC to accomplish this task. 

Authentication 

The RPC protocol provides the fields necessary for a client to identify itself to a 
service and vice-versa. Security and access control mechanisms can be built on 
top of the message authentication. Several different authentication protocols can 
be supported. A field in the RPC header specifies the protocol being used. 
More information on authentication protocols can be found in the "Authentica- 
tion Protocols" section, below. 
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Organization of Teciinical Information 

The "RFC Protocol Requirements" section outlines the inherent features of the 
RFC protocol and additional features provided by the RPC package. 

The "RPC Message Protocol" section defines the RPC message protocol in terms 
of the XDR language. 

The "Authentication Protocols" section describes authentication features sup- 
ported by the RPC package. 

The "Record Marking Standard" section describes how RPC messages are 
delimited from each other when operating over a byte stream protocol transport 
like TPC/IP. 

'The RPC Language" section provides an example of an RPC service followed 
by a formal definition of the FPC language. 

The "rpcbind Protocol" section describes the interface to the rpcbind service. 
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The RPC protocol provides for the following: 

■ Unique specification of a procedure to be called. 

■ Provisions for matching response messages to request messages. 

■ Provisions for authenticating the caller to service and vice-versa. 
In addition, the RPC package provides features that detect the following: 

■ RPC protocol nusmatches. 

■ Remote program protocol version mismatches. 

■ Protocol errors (such as nusspecification of a procedure's parameters). 

■ Reasons why remote authentication failed. 

Programs and Procedures 

The RPC call message has three unsigned fields: 

■ remote program number 

■ remote program version number 
m remote procedure number 

The three fields uniquely identify the procedure to be called. 

Program numbers are administered by a central authority (see below). 

The first implementation of a program will most likely have version number 1. 
Because most new protocols evolve into better, stable, and mature protocols, a 
version field of the call message identifies the version of the protocol the caller 
is using. Version numbers make speaking old and new protocols through the 
same server process possible. 

The procedure number identifies the procedure to be called. These numbers are 
documented in the specific program's protocol specification. For example, a file 
service's protocol specification may state that its procedure number 5 is "read" 
and procedure number 12 is "write." 
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Just as remote program protocols may change over several versions, the RPC 
message protocol itself may change. Therefore, the call message also has in it 
the RPC version number, which is always equal to 2 for the version of RPC 
described here. 

The reply message to a request message has enough information to distinguish 
the following error conditions: 

■ The remote implementation of RPC does not speak protocol version 2. 
The lowest and highest supported RPC version numbers are returned. 

■ The remote program is not available on the remote system. 

■ The remote program does not support the requested version number. The 
lowest and highest supported remote program version numbers are 
returned. 

■ The requested procedure number does not exist. (This is usually a caller 
side protocol or programming error.) 

■ The parameters to the remote procedure appear to be garbage from the 
server's point of view. (Again, this is usually caused by a disagreement 
about the protocol between client and service.) 



Authentication 

Provisions for authentication of caller to service and vice-versa are provided as a 
part of the RPC protocol. The call message has two authentication fields, the 
credentials and verifier. The reply message has one authentication field, the 
response verifier. The RPC protocol specification defines all three fields to be 
the following opaque type: 
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enum authjfXavor { 







0, 














AQTHJXE3 




3 


/* 4mS WOlse t< 


> t>4 



/* 9dd]Pd33 of iK>xe «ut)): stuff 
not to cdcciddd M»x Hmc smss V 



In simple English, any opaque_auth structure is an auth_f lavor enumera- 
tion followed by bytes that are opaque to the RPC protocol implementation. 

The interpretation and semantics of the data contained within the authentication 
fields is specified by individual, independent authentication protocol 
specifications. (See "Authentication Protocols," below, for definitions of the 
various authentication protocols.) 

If authentication parameters are rejected, the response message contains infor- 
mation stating why they are rejected. 



Program Number Assignment 

Program numbers are given out in groups of 0x20000000 according to the fol- 
lowing chart: 
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Program Numbers 



Description 



20000000 
40000000 
60000000 
80000000 
aOOOOOOO 
cOOOOOOO 
eOOOOOOO 



0 



Ifffffff 
3fffffff 
Sfffffff 
7fffffff 
9fffffff 
bfffffff 
dfffffff 
ffffffff 



Defined by Sun 
Defined by user 



Transient 
Reserved 
Reserved 
Reserved 
Reserved 
Reserved 



Sun Microsystems administers the first group of numbers, which should be 
identical for all UNIX® System V customers. If a customer develops an applica- 
tion that nught be of general interest, that application should be given an 
assigned number in the first range. 

The second group of numbers is reserved for specific customer applications. 
This range is intended primarily for debugging new programs. 

The third group is reserved for applications that generate program numbers 
dynamically. 

The final groups are reserved for future use, and should not be used. 

To register a protocol specification, send a request by email to rpc@sun. com, 
or write to: 

RPC Administrator 
Sun Microsystems 
2550 Garcia Ave. 
Mountain View, CA 94043 

Please include a compilable rpcgen . x file describing your protocol. You will 
be given a unique program number in return. 

The RPC program numbers and protocol specifications of standard RPC services 
can be found in the include files in /usr/include/rpcsvc. These services, 
however, constitute only a small subset of those that have been registered. 
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Other Uses of the RPC Protocol 

The intended use of this protocol is for calling remote procedures. That is, each 
call message is matched with a response message. However, the protocol itself 
is a message-passing protocol with which other (non-RPC) protocols can be 
implemented. Some of the non-RPC protocols supported by the RPC package 
are: 

Batching 

Batching allows a client to send an arbitrarily large sequence of call messages to 
a server; batching typically uses relialjle byte stream protocols (like TCP/IP) for 
its transport. In batching, the client never waits for a reply from the server, and 
the server does not send replies to batch requests. A sequence of batch calls is 
usually finished by a non-batch RPC call to flush the pipeline (with positive ack- 
nowledgement). 

Broadcast RPC 

In broadcast RPC-based protocols, the client sends a broadcast packet to the net- 
work and waits for numerous replies. Broadcast RPC uses unreliable, packet- 
based protocols (like UDP/IP) as its transports. Servers that support broadcast 
protocols only resp>ond when the request is successfully processed, and are 
silent in the face of errors. Broadcast RPC uses the rpcbind service to achieve 
its semantics. See the "rpcbind Protocol" below, for more information. 
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This section defines the RPC message protocol in the XDR data description 
language. The message is defined in a top-down style. 

(■ ' \ 

""cm * 0^ 

lllllllllllllllillii 

* A reply to a call message can take <m two fojaw; 
The message itras either accepted or rejected, 

envmv reply^stat { 

iiiiiiiiiiiliiiiiiliiiiiiiiiili^^ 

* Given that a call message was aoo^ted, the following is the 

* Status Of an atten^t to caXX a tsemote procedure. 

enqm accept^stat { 

StXXESS - Or /♦ BPC executed successfully */ 
PBOGJONKVAIL « 1, /* remote hasn't exported program 
PROG^MISMAICH ** 2, /* remote catt't support version # V 
PRCXMJNAVAIL » 3, /♦ program can't support procedure */ 
G?«Bi»GEJ&RGS •« 4 /♦ procedure can't decode params */ 



* Reasons why a call message was rejected: 

enum re ject__stat { 

PPCMISMATCH - 0, /* RPC version number 2 */ 
ADTHjawOR » 1 /* remote can't authenticate caller */ 

liiiliiiiiiiiiilliliil 



* Why authentication failed: 

enum aijthjjtat { 

AOTH_BADCRBD * 1, /* bad credentials */ 

AUTHJtEJECIEDCRED ^2, /* client must begin new session V 

AtmTBMJVERF ^3, /* bad verifier */ 

ADTH__REJECTEDVfiRF *• 4, /* verifier expired or replayed */ 

KSjss. TOOWEAK - 5 /* rejected for security reasons */ 
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iiiiiiiiiiiiiiiiilliiiilli^ 

* TO» message; 

« ^1 toessages start with a transaction Id^tlfier^ add, 
^ fQllQMed |>y a t%fo^arniadl discriminatecl union » The union's 

* discriminant is a niscf_type which switches to one of the two 

* tyjpes of the message . Ihe xid Of a KEPLY massage always 
^ matches that of the Initiating CALL message t MB; %e xid 

* field is only \ised for clients matching r^ly messages with 

* call messages or for servei^ detecting xetransmissicxiS; the 

* service side cannot treat this id as any type of sequence 

* nuwber. 

struct rpcjnsg { 

unsi^ped int xid; 
union switdi (msg_type mtype) { 
case CALL: 

calljxxly cbody; 
case REPLY: 

tepXyJxxSy rbody; 

} My; 

liiiiiiiB^^ 

* Body of an RPC request call: 

* In Version 2 of the RPC pl^otocol specification, rpcvers mttst 

* he equal to 2. The fields prog# vers^ and proc specify the 

* remote program^ its version nusiber, and the procedure within 

* the remote program to he called < After these fieldlB are two 

* authentication parameters: cred {authentication credentials) 
^ and verf (authentication verifier) . The two authentication 

* parameters are followed by the parameters to the remote 
^ procedure, lAtich are specified by the specific program 

* protocol. 

struct calljjody { 

unsigned int rpcvers; /* mast be equal to two (2) */ 

wisigned int prog; 

lihsigned int Vers; 

unsigned int proc; 

opaqoe^auth cred; 

opaqtle_auth verf; 

/* procedure specific parameters start here */ 

V J 

(continued on next page ) 
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lllllllllllllllillll 

* iBody of h x^ply to m ft&C i?8goe*ti 

* yhe caXX m&ss^^ was etthei? acceptwi or rejected. 

union replyj^ody switch. (rBply_^stat 5t«t) ( 
case 

acc€^ted_teply areply,' 
case H5G_DENIED; 

rejected^reply xxeipXy; 

iiiiiiiiiiiiiiiiiiiiii^ 

* Reply to an RPC request that %ia3 aco^ed by the server; 

* there couXd be an error even though the request was accepted. 

* The first field is ah authehtication verifier that the aerver 

* <feneratea In orc^r to validate itself to the caller. It is 

* followed by a union *rtjose discriminant is an mm 

* acCept^stat, The S0CX3ESS atta of the union la protocol 

* specific. The PRDGJJMAVAIL, PROCJONftWAIL, and GARBftGEJ^GP 

« axms of the union are void. !Che i^DGHIStA^ arm apecifiea 

* the lowest and highest version numbera of the remote program 

* supported by the server^ 

llllllllllllllll^^^^^^^ 

struct acoe|>tedLreply { 

opaquejauth verf ; 
union switch <ac6ept_stat stat) { 
case SXXX^ESSt 

opaque results tO}; 

/* procedure^specific results start; here */ 

case ^msjastmscai 
struct ( 

unsigned int low; 
unsigned int high; 
) mismatch_info; 

default: 

* Vold^ Cases Include PBOGJAOVKIL, PR0CJ3M»!(AIL, 

* and GRRBftGE itcs, 

illlllllllliili;!:;!^ 

void; 

> reply data; 
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* Sto(>ly to ith xidC(u^t th^t Wdid to^wstod by the de£veri 

* 'mm «equ«9t c«n be ^rejected tox tw9 ve«wKm»: «ithe«r the 
^ jsexver Is not running a compatible varslOKi of the HPC 

protocol (RPCJdSIATCH) , or the 9erver xefu3e3 to 

* authenticate the caller (APTHJ!PPOa> * In case of an RPC 

* veziftlon miattnatdv, the aert^ retutnft tha lOMiadt ^ high^ 

* supported BFC verffion number^, In ca9e O^ refuaect 

* authentication^ failure status id returned. 



union rejected^reply switcdt (rejectjstat stat^ 
case BPCJCSM^TCH: 
atruct { 

ixnsigned int low; 
msigfii&i Int hi0i; 
} jniamatch^info; 

ease 

Ittithjstat stat«' 
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As previously stated, authentication parameters are opaque, but open-ended to 
the rest of the RFC protocol. This section defines some flavors of authentication 
that have already been implemented. Other sites are free to invent new authen- 
tication types, with the same rules of flavor number assignment as there is for 
program number assignment. 

AUTH_NONE Authentication 

Calls are often made where the caller does not authenticate itself and the server 
does not care who the caller is. In these cases, the flavor value (the "discrim- 
inant" of the opaque_auth "union") of the RFC message's credentials, verifier, 
and response verifier is AUTH_NONE. The bytes of the body field in the 
opaque_auth structure are undefined. It is recommended that the body 
length be zero when AUTH_NONE authentication is used. 

AUTH SYS Authentication 

The caller of a remote procedure may wish to identify itself using traditional 
System V process permissions authentication. The flavor of the 
opaque_auth of such an RFC call message is AUTH_SYS. The bytes of the 
body encode the following structure: 













Btxtjct suth^ayspaCTW { 








uxldlgAidd lAt dtainp; 






string mac*ii»ei>ame<»55>; 






uldjt: uld; 








gi4jt intgl^i; 








gidt int gld3<ia>; 


V 






J 



Stamp is an arbitrary ID that the caller machine may generate, 

machinename is the name of the caller's machine (like "krypton"). 
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uid is the caller's effective user ID. 

gid is the caller's effective group ID. 

gids is a counted array of groups in which the caller is a 

member. 

The flavor of the verifier accompanying the credentials should be 
AUTH_NONE. (defined above). 

The AUTH SHORT Verifier 

When using AUTH__SYS authentication, the flavor of the response verifier 
received in the reply message from the server may be AUTH_NONE or 
AUTH_SHORT. 

If AUTH_SHORT, the bytes of the response verifier's string encode a 
short_hand__verf structure. This opaque structure may now be passed to the 
server instead of the original AUTH__SYS credentials. 

The server keeps a cache that maps shorthand opaque structures (passed back 
by way of an AUTH_SHORT style response verifier) to the original credentials of 
the caller. The caller can save network bandwidth and server cpu cycles by 
using the new credentials. 

The server may flush the shorthand opaque structure at any time. If this hap- 
pens, the remote procedure call message will be rejected owing to an authentica- 
tion error. The reason for the failure vdll be AUTH_REJECTEDCRED. At this 
point, the caller may wish to try the original AUTH_SYS style of credentials. 



AUTH DES Authentication 

AUTH_SYS authentication suffers from the following problems: 

■ Caller identification can not be guaranteed to be unique if machines with 
differing operating systems are on the same network. 

■ There is no verifier, so credentials can easily be faked. 
AUTH_DES authentication attempts to fix these two problems. 
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Naming 

the first problem is handled by addressing the caller by a simple string of char- 
acters instead of by an operating system specific integer. This string of charac- 
ters is known as the netname or network name of the caller. The server should 
not interpret the caller's name in any way other than as the identify of the 
caller. TTius, netnames should be unique for every caller in the naming domain. 

It is up to each operating system's implementation of AUTH_DES authentication 
to generate netnames for its users that insure this uniqueness when they call 
remote servers. Operating systems already know how to distinguish users local 
to their systems. It is usually a simple matter to extend this mechanism to the 
network. For example, a user with a user ID of 515 might be assigned the fol- 
lowing netname: "UNIX . 5150 sun . com". This netname contains three items 
that serve to insure it is unique. Going backwards, there is only one naming 
domain called sun . com in the internet. Within this domain, there is only one 
UNIX user with user ID 515. However, there may be another user on another 
operating system, for example VMS, within the same naming domain that, by 
coincidence, happens to have the same user ID. To insure that these two users 
can be distinguished we add the operating system name. So one user is 
"UNIX.5150sun.com" and the other is "VMS.515@sun.com". 



NOTE 



The first field is actually a naming method rather than an operating system 
name. It just happens that today there is almost a one-to-one correspon- 
dence between naming methods and operating systems. If the world could 
agree on a naming standard, the first field could be a name from that stan- 
' dard, instead of an operating system name. 

AUTH DES Authentication Verifiers 

Unlike AUTH_SYS authentication, AUTH_DES authentication does have a verifier 
so the server can validate the client's credential (and vice-versa). The contents 
of this verifier is primarily an encrypted timestamp. The server can decrypt this 
timestamp, and if it is close to what the real time is, then the client must have 
encrypted it correctly. The only way the client could encrypt it correctly is to 
know the conversation key of the RFC session. If the client knows the conversa- 
tion key, then it must be the real client. 

The conversation key is a DES [5] key that the client generates and notifies the 
server of in its first RFC call. The conversation key is encrypted using a public 
key scheme in this first transaction. The particular public key scheme used in 
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AUTH_DES authentication is Diffie-Hellman [3] with 192-bit keys. The details of 
this encryption method are described later. 

The client and the server need the same notion of the current time for this to 
work. If network time synchronization cannot be guaranteed, then client can 
synchronize with the server before beginning the conversation, perhaps by con- 
sulting the Internet Time Server [4]. 

A server can determine if a client timestamp is valid. For any transaction after 
the first, the server checks for two things: 

■ the timestamp is greater than the one previously seen from the same 
client 

■ the timestamp has not expired 

A timestamp is expired if the server's time is later than the sum of the client's 
timestamp plus what is known as the client's window. The window is a number 
the client passes (encrypted) to the server in its first transaction. The window 
can be thought of as a lifetime for the credential. 

For the first transaction, the server checks that the timestamp has not expired. 
As an added check, the client sends an encrypted item in the first transaction 
known as the window verifier which must be equal to the window minus 1, or 
the server will reject the credential. 

The client must check the verifier returned from the server to be sure it is legiti- 
mate. The server sends back to the client the encrypted timestamp it received 
from the client, nunus one second. If the client gets anything other than this, it 
will reject it. 

Nicknames and Clock Synchronization 

After the first transaction, the server's AUTH_DES authentication subsystem 
returns in its verifier to the client an integer nickname that the client may use in 
its further transactions instead of passing its netname, encrypted DES key and 
window every time. The nickname is most likely an index into a table on the 
server that stores for each client its netname, decrypted DES key and window. 

Though originally synchronized, client and server clocks can get out of sync. If 
this happens, the client RFC subsystem most likely will get back 
RPC_AUTHERROR at which point it should resjmchronize. 
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A client may still get the RPC_AUTHERROR error even though it is synchronized 
with the server. The reason is that the server's nickname table is a limited size, 
and it may flush entries whenever it wants. The client should resend its origi- 
nal credential and the server will give it a new nickname. If a server crashes, 
the entire nickname table may get flushed, and all clients will have to resend 
their original credentials. 



DES Authentication Protocoi (in XDR language) 



* thesa axe two kinds of cxadeintials: one in which th^ <:Ii^t used 
A its full network nams, anci one in vhUAi it uses its "niqkname" 

* (just m unsigned integer) given to it by the server. She 

* client nust use its fullname in its first transaction with the 

* server in which the server wiil return to the client its 

* nicknajne. The client may use its nickname in all further 

* transactions %dth the server » !Ehere is no zequlrement to use the 

* nlcknajwe, but it is wise to use it for perfomnance reasons . 
Illllllllll^^^^ 

enum authdasjiamekind ( 

immjmm - o, 
MMvicxmm m 1 

* A ^4-bit block of encrypted tMBS data 
typedef opaque dMj>lock{83; 

* Maximum length Of a network user^s nane 

const MAXHetHAMEUSKf m 2S5; 

lllllllllll 

^ A fullname contains the network name of the client^ an encrypted 

* conversatiori key and the window, the window is actually a 

* lifetilae for the credential. If thd time indicated in the 

* verifier ti»estairp plus the window has passed/ then the server 

* should expire the request and not grant it. To insure that 

* requests are not replayed/ the server should insist that 

* tlinestanips be greater than the previous one seen^ unless it is 

* the first transactiOtt. Xa the first transaction, the server 

* checks instead that the window verifier is one less than the 

* vlndow. 



(continued on next page ) 
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atring nw^©<HAXME?TWiMfia^^ /* nww of client ♦/ 

liiiiiii^iiiiiiiiiiii 

union anthdatfjsrdd switch (authdddjtamidJcind adejnaiiMdcind) ( 
auth<)dfljCaiXn«roe adc fuilnama; 
im^ignecil int a^ksjiicknaRi^; 

|||||||||||||;||||| 

^ A timsatamp ^<s(^d thd tikna sinde ifctdni^ht. ^aiuiaxy 1, 197Q. 

iliiiiiiiiiiiiiiiiiiiii 

imai^nod int aecond?; 
imai^pied int uaeconda; 

iiiliillilili^^ 



/* awJ micixmecciiida */ 



* V03!rifi©rs client variety 

liiiiiiiiiB^^^ 

tlm^stm^ advj:iinastawp; 
unai^^Tkad int advwinvdxf ; 



/* encrypted tlwestan^j */ 
encrypted ytindditt verifier ^/ 



* Verifiers server variety 

^ the server returns (encrypted) the same tiznestanp the client 

* gam it minims one seccaid. It also tells the client its nickname 

* to S5e used in future transaeticstis tvinencrypted]! » 



stCTK* attthdesjwflripjwrr ( 

tii(iesLtii$i>lidvj:i«i6verf,' 
unsigned int advjiiclcnaRie; 



/* encrypted verifier */ 
/* new nickname for client */ 
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Diffie-Hellman Encryption 

In this scheme, there are two constants, PROOT and HEXMODULUS. The particu- 
lar values chosen for these for the DES authentication protocol are: 

eottdt PBOOt ^ 3; 

qon^t; "SSBXXXXJU^ •» "44a0baO2$0b6f<^ec6:^$Bl^d637d£7^7l«e22dO^44b88b";^ h^ac 

J 

The way this scheme works is best explained by an example. Suppose there are 
two people "A" and "B" who want to send encrypted messages to each other. 
So, A and B each generate a random secrei key that they do not disclose to any- 
one. Let these keys be represented as SK(A) and SK(B) . They also publish in 
a public directory their public keys. These keys are computed as follows: 

PK(A) = ( PROOT ** SK(A) ) mod HEXMODULUS 
PK(B) = ( PROOT ** SK(B) ) mod HEXMODULUS 

The ** notation is used here to represent exponentiation. 

Now, both A and B can arrive at the common key between them, represented 
here as CK (A, B) , without disclosing their secret keys. 

A computes: 

CK(A, B) - ( PK(B) ** SK(A)) mod HEXMODULUS 
while B computes: 

CK(A, B) = ( PK(A) ** SK(B)) mod HEXMODULUS 
These two can be shown to be equivalent: 

(PK(B)**SK(A)) mod HEXMODULUS = (PK (A) **SK (B) ) mod HEXMODULUS 

We drop the mod HEXMODULUS parts and assume modulo arithmetic to sim- 
plify things: 

PK(B) ** SK(A) = PK(A) ** SK(B) 

Then, replace PK (B) by what B computed earlier and likewise for PK (A) . 
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((PROOT ** SK(B)) ** SK(A) - (PROOT SK(A)) ** SK(B) 
which leads to: 

PRCX)T ** {SK(A) * SK(B)) » PROOT ** (SK(A) * SK(B)) 

This common key CK (A, B) is not used to encrypt the timestamps used in the 
protocol. It is used only to encrypt a conversation key that is then used to 
encrypt the timestamps. The reason for doing this is to use the common key as 
little as possible, for fear that it could be broken. Breaking the conversation key 
is a far less serious offense, because conversations are comparatively short-lived. 

The conversation key is encrypted using 56-bit DES keys, yet the common key is 
192 bits. To reduce the number of bits, 56 bits are selected from the common 
key as follows. The middle-most 8-bytes are selected from the common key, 
and then parity is added to the lower order bit of each byte, producing a 56-bit 
key with 8 bits of parity. 
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When RPC messages are passed on top of a byte stream protocol (like TCP/IP), 
it is necessary, or at least desirable, to delimit one message from another to 
detect and possibly recover from user protocol errors. This is called record 
marking (RM). One RPC message fits into one RM record. 

A record is composed of one or more record fragments. A record fragment is a 
four-byte header followed byOto (2**31) - 1 bytes of fragment data. The 
b3^es encode an unsigned binary number; as with XDR integers, the byte order 
is from highest to lowest. 

The header encodes two values 

■ a boolean that specifies whether the fragment is the last fragment of the 
record (bit value 1 implies the fragment is the last fragment) 

■ a 31-bit unsigned binary value that is the length in bytes of the fragment's 
data. 

The boolean value is the highest-order bit of the header; the length is the 31 
low-order bits. 



ii||pl This record spGcification is not in XDR standard form. 
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Just as there was a need to describe the XDR data-types in a formal language, 
there is also need to describe the procedures that operate on these XDR data- 
types in a formal language as well. We use the RPC Language for this purpose. 
It is an extension to the XDR language. The following example is used to 
describe the essence of the language. 



An Example Service Described in the RPC Language 

Here is an example of the specification of a simple ping program. 



* Ping thd csXXer, i?etiim th^ round-trip tim^ 

* {in jniczoseGonds)l . Betuxns -1 if the operation 

* timed out. 



/* 

* Original version 



version pimyessi&jm& { 



^ - 1; 



) - 1; 



\ aooooo; 

const PING VERS - 2; /* X^test WSfion ♦/ 
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The first version described is PING_yERS_PINGBACK with two procedures, 
PINGPROC_NULL and PINGPROC_PINGBACK. 

PINGPROC__NULL takes no arguments and returns no results, but it is useful for 
such things as computing round-trip times from the client to the server and 
back again. By convention, procedure 0 of any RPC protocol should have the 
same semantics, and never require authentication. 

The second procedure is used for the client to have the server dp a reverse ping 
operation back to the client, and it returns the amount of time (in microseconds) 
that the operation used. 

The next version, PING_VERS_ORIG, is the original version of the protocol and 
it doe^ not contain PINGPROC_PINGBACK procedure. It is useful for compatibil- 
ity with old client programs, and as this program matures it may be dropped 
from the protocol entirely. 

The RPC Language Specification 

The RPC language is identical to the XDR language, except for the added 
definitions described below. 
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program-definiHon: 

program program-ident { 

version-list 
} « value 

version-list: 

version ; 

version ; version-list 

version: 

version version-ident { 

procedure-list 
) rvalue 

procedure-list: 

procedure ; 

procedure ; procedure-list 
procedure: 

type-ident procedure-ident { type-ident ) = value 



Syntax Notes 

1. The following ke5words are added and cannot be used as identifiers: 

program version 



2. A version name cannot occur more than once within the scope of a pro- 
gram definition. Nor can a version number occur more than once within 
the scope of a program definition. 

3. A procedure name cannot occur more than once within the scope of a 
version definition. Nor can a procedure number occur more than once 
within the scope of version definition. 

4. Program identifiers are in the same name space as constant and type 
identifiers. 

5. Only unsigned constants can be assigned to programs, versions and pro- 
cedures. 



Remote Procedure Calls: Protocol Specification 



9-25 



rpcbind Protocol 



rpcbind maps RPC program and version numbers to universal addresses, thus 
making dynamic binding of remote programs possible. 

rpcbind is run at a well-known universal address, and other programs register 
their dynamically allocated transport addresses with it. It then makes those 
addresses publically available. Universal addresses are defined by the address- 
ing authority of the given transport. They are string representations of the tran- 
sport address. 

rpcbind also aids in broadcast RPC. There is ho fixed relationship between 
the addresses that a given RPC program will have on different machines, so 
there is no way to broadcast directly to all these programs, rpcbind, however, 
has a universal address. So, to broadcast to a given program, the client actually 
sends its message to the rpcbind process on the machine it wishes to reach, 
rpcbind picks up the broadcast and calls the local service specified by the 
client. When rpcbind gets a reply from the local service, it passes it on to the 
client. 



rpcbind Protocol Specification (in RPC Language) 



* RPCBIND ptotocoX in tpc Xjsngttdge 



* A nia|>ping of (program, version, network. ID) to universal address 

struct rpcto { 

u^long rjprog; /* program nuinber */ 

u^lotig rjwera; /* version nywiber */ 

string rjietidO; /* network id */ 

stTing r addrO; /* wiiversal address */ 

iliiii^iiliiilii^^^ 

111111111111111;^ 

* A list of mappings 

struct rpdblist ( 



(continued on next page ) 
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xpcib rpcbjwap; 

struct xpcblist *rp<a5jio*t; 



* Arguments Of remote calls 



struct rpcb_nntcallargs ( 
u_lor>g prog; 
uJLong vers; 
u_long proc; 
opaque argsjptro; 

}; 



/* program number */ 
/* version number */ 

procedure number */ 
/* argument */ 



;^||||||;|;||| 
* Results of the remote call 

struct rpcb^rmtcallres { 

string a<3(3rjptrO; /* remote universal adcSress */ 

opacpae results jptro; /* result */ 



* rpcbind procedures 
*/ 

program RPCBPROG { 

version RPCBVERS { 
void 

.: RPCBPROC_NULL(vo±d) - 0; 
bool 

RPCBPROC_SET(rpcb) - 1; 



bool 

RPCSPROCJJNSET (rpcb) - 2; 
string 

RPCM>R0Cj3ETADDR(rpcb) -3; 
rpcblist 

R£>C^ROCJ)UME>(void> - 4; 
rpcb__rmtcallres 

!^C^iW_aai.XT (rpcb^rmtcallargs) ^ 5; 



unsigned Int 



(continued on next page ) 
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> - 3; 

100000; 



struct netljuf 
string 

RPCSPB0G_tEADl>R2tftI^ (struct netbuf) » B; 



rpcbind Operation 

rpcbind is contacted by way of an assigned address specific to the transport 
being used. For IP, for example, it is port number 111. Each transport has such 
an assigned well known address. The following is a description of each of the 
procedures supported by rpcbind. 

The RPCBPROC^NULL Procedure 

This procedure does no work. By convention, procedure zero of any protocol 
takes no parameters and returns no results. 

The RPCBPROC SET Procedure 

When a program first becomes available on a machine, it registers itself with the 
rpcbind program running on the same machine. The program passes its pro- 
gram number prog, version number vers, network identifier netid, and the 
universal address uaddr on which it awaits service requests. 

The procedure returns a boolean response whose value is TRUE if the procedure 
successfully established the mapping and FALSE otherwise. The procedure 
refuses to establish a mapping if one already exists for the tuple (prog, vers, 
netid). 
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Note that neither netid nor uaddr can be NULL, and that netid should be a valid 
network identifier on the machine making the call. 

The RPCBPROC.UNSET Procedure 

When a program becomes unavailable, it should unregister itself with the 
rpcbind program on the same machine. 

The parameters and results have meanings identical to those of RPCBPROC_SET. 
The mapping of the (prog, vers, netid) tuple with mddr is deleted. 

If netid is NULL, all mappings specified by the tuple (prog, vers, *) and the 
corresponding universal addresses are deleted. 

The RPCBPROC_GETADDR Procedure 

Given a program number prog, version number vers, and network identifier 
netid, this procedure returns the universal address on which the program is 
awaiting call requests. 

The netid field of the argument is ignored and the netid is inferred from the netid 
of the transport on which the request came in. 

The RPCBPROC_,DUMP Procedure 

This procedure lists all entries in rpcbind's database. 

The procedure takes no parameters and returns a list of program, version, netid, 
and universal addresses. 

The RPCBPROC^CALLIT Procedure 

This procedure allows a caller to call another remote procedure on the same 
machine without knowing the remote procedure's universal address. It is 
intended for supporting broadcasts to arbitrary remote programs via rpcbind's 
universal address. 

The parameters prog, vers, proc, and the argsjptr are the program number, ver- 
sion number, procedure number, and parameters of the remote procedure. 
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mm 



This procedure only sends a response if the procedure was successfully 
executed and is silent (no response) otherwise. 



The procedure returns the remote program's universal address, and the results 
of the remote procedure. 

The RPCBPROC^^GETTIME Procedure 

This procedure returns the local time on its own machine. 
The RPCBPR0C^UADDR2TADDR Procedure 

This procedure converts universal addresses to transport (netbuf ) addresses. 
RPCBPR0C_UADDR2TADDR is equivalent to uaddr2taddr() [see netdir(3N)]. 



NOTE 



Only processes that can not link to the name-to-address library modules 

should use RPCBPROC UADDR2TADDR. 



The RPCBPR0C_^TADDR2UADDR Procedure 

This procedure converts transport (netbuf) addresses to universal addresses. 
RPCBPR0C__TADDR2UADDR is equivalent to taddr2uaddr() [see netdir(3N)]. 



NOTE 



Only processes that can not link to the name-to-address library modules 
should use rpcbproc taddr2uaddr. 
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Introduction to RPC Administration 

RFC administration consists of configuring administration files that: 

■ Establish name-to-address mapping relationships 

■ Start server daemons at boot time 

■ Prompt users for a network password at login (secure RPC) 

■ Edit a master machine /etc/publickey file that determines who can 
access secure RPC services (secure RPC) 

■ Start 3^aemons 

Servers are started at boot time by editable system RC scripts. The file 
/etc/profile is edited to call keylogin to query for a network password at 
login time. 

YP is currently the recommended default mechanism for administering secure 
RPC (see Chapter 11, 'The YP Service"). 
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Name-to-Address IVIapping 

Name-to-address mapping must be in effect for RPC (secure or otherwise) to 
work. Refer to the "Network Services" chapter of the System Administrator's 
Guide for name-to-address mapping administrative procedures. 

System RC File /etc/rc2.d/s75rpc 

RPC servers can be started at system boot time. When the system comes up in 
init state 2, all of the scripts in /etc/rc2 . d are executed. One of these scripts, 
/etc/rc2.d/s75rpc, starts the RPC servers. 

The system administrator can edit the script to start additional servers. For 
reference, the default script, shipped with new systems, is shown here: 

#icJent -@(#)liiitpkg:lnit.d/rpc 1,1,2,5" 
if [ ! -d /usr/bin ] 

then # /usr not mounted 

lllllllllllllllllllllli 

c^ise •'$X** in 

set *who ^r^ 

if [ 419 - ^S** -0 $9 - "1" $9 ' 3 
If I -X Aisr/sbln/rpc4>lnd j 

/sbin/sh /etc/init .d/rpc rpcstartfi 

else 

exit i nothing else can do anything 

iiiilSiliililililiiiilil^ 

/u^r/abin/rpcbind > /dev/console i>&l 

it [ /i3sr/lib/netavc/twall/rpc.rwalld ] 
then 

/tisr/lib/netsvc/rwall/xpc.rwalld > /dev/consoXe 2>«X 

iillllllillllllllllll^^ 

if r /usx/lib/netsvc/ru3ers/3:pc.rusersd } 

V ^ 

(continued on next page ) 
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/udr/lib/ndtsvc/xaderd/xpc.ruaeraKi > /<tev/consoX^ 2>n 

iiiiiiiiiiiiiiiiiiiliiiiili^l^ 

then 

/usr/lib/netavc/spray/rpc.sprayd > /dev/console i>&l 

unconment f pr seciaxe RFC 

if t "-St /uar/sbin/keyserv ] 
then 

/lidr/sblnAfeyaerv > /dev/console 2>«l 
±f { /u9r/Xlb/netsvc/yp/yj*>ind J 

/usr/lib/netavc/yp/ypbind > /dev/console 2>&1 

if ( -X /usr/lib/netsvc/^/ypupdated 1 

;i;;tiii^|||;||||| 

/usr/lib/netsvc/yp/ypupdated > /dev/console 2>*X 

if [ -X /ugr/lib/netsvc/yp/ypserv ] 
then 

/osr/lib/netsvc/yp/ypserv > /dev/console 2>A1 

lilliiiiiiliiiiliiii 



#stop aU t^e daattons 

pi^Vuyr/bin/ps J /usr/bln/grep rpc.spra 1 \ 
/U5r/bin/3ed --e 's/'^ ♦//' '3/ ,*//' 
1£ r *'${pid)* J- 1 



then 



/usr/bln/kllX $^pid> 



pid-Vusr/bin/ps \ /usr/bln/gxep rpc.ruse I \ 

/usr/bin/sed -e 's/'^ *//' -e 's/ .*//" 
if { "${pid}" !- ''^ ] 
then 

/uat/bln/kllX $|pid) 

pld-Vusr/bin/ps -e T /usr/bln/grep xpcwaX \ \ 

/uar/bin/aed -e 's/'^ *//' 's/ .*//^^ 
if [ "$^pid}" 1- 1 
then 

fi 



/usr/bln/klll ${pid} 



(continued on next page ] 
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pid-Vu5r/bin/ps \ /usr/bin/grep rpcbittd ( \ 
/usr/bin/sed -e 'a/* *//^ -e 's/ 

if I "^cpicar 3 

/usr/bin/kill ${pid> 

# imcaiment for secure RPC 

# pid*Vuar/bin/p3 -e [ /usr/hin/grep keyserv ( \ 

/uar/bin/aed 's/'' *//' -e '3/ ,*//' ' 
if ( ^•Sfpidr ?- I 
then 

/uar/bin/kill ${pid} 

llllllllllllllllll 

pid«Vusr/bin/ps -e I /usr/bin/grep ypbind } \ 

/uar/biti/sed -e 's/^ *//' 'a/ 
if t ''${pidr !- 3 
then 

/uar/bin/kill ${pid} 

pid-^/uar/bin/ps -e I /usr/bin/gre^ ypapdated I \ 
/uar/bln/sed 'a/'^ *//' -e ^3/ >//' ^ 
if [ "5(pidJ'» «- 1 
th^ 

/usr/bin/kill ${pid) 

pid-Vusr/bin/ps -e } /uar/bin/grep ypserv I \ 

/usr/bin/sed --e 'a/'^ *//' -e ^s/ .♦//' * 
if [ "^{pidr I- J 
then 

/U3r/bin/kill ${pid} 



*) 










echo •♦Oaage: /etc/initrd/rpc ( 3tart \ 


stop 


eaac 
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The server keyserv must also be running for secure RPC to work properly. 
Administrators may wish to edit the RPC RC script to start keyserv at iDOOt 
time. If not, keyserv will have to be started manually or by other means. 



The /etc/publickey File 

Secure RPC information is kept in this file, which is controlled by a domain 
master server. For each secure RPC user known to a master, this file contains: 

■ operating system name 

■ user ID 

■ RPC domain name 

■ public key 

■ secret key 

The triple (operating system, user ID, domain) forms a unique key into this data- 
base of public/secret key pairs that are required by the RPC built-in security 
protocol. 



NOTE 



The user ID field in /etc/publickey may also be a host name. This 
allows more than one root user per domain. 



The /etc/master.d/kernel File 

All machines supporting secure RPC must have what is known as a secure RPC 
domain name. By default, a machine's secure RPC domain name is null and 
(because it is null), secure RPC will not work on the machine. 

A domain name can be set using the domainname(lM) command, but it will 
not be remembered across reboots. For preservation of the name across reboots, 
administrators need to edit their /etc/master . d/kerhel file to set the 
SRPC__DOMAIN tunable to their desired secure RPC domain name. For example. 
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to change a machine's domain name from null to finance, the system adminis- 
trator would find the line: 

SRPC_DOMAIN-"" 

in /etc/master .d/kernel and change it to 

SRPC DOMAIN*" finance" 
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There is a security protocol, based on DES encryption, built into the RPC pack- 
age. Remote programs that use secure RPC expect client users to have a 
pubhc/secret key entry in a shared master /etc/publickey file. Access to 
secure RPC programs is controlled by the keyserv daemon which accesses the 
/etc/publickey file when users invoke keylogin. One /etc/publickey 
database exists for each secure RPC domain. In large domains (many 
machines), multiple physical copies of the database may exist for performance 
reasons. If multiple copies exist, updates will be made to the copy on the 
domain's master server, and copies of the master /etc/publickey will be 
propagated to slave servers. 

Secure RPC users must be given entries in this file on the master 
/etc/publickey server machine by the system administrator before they can 
use secure RPC programs (in that domain). These users must also be given 
logins on the master server machine. 

In addition, the administrator of every client machine should edit 
/etc/profile to remove the comment character that has commented out the 
keylogin command; in this way, keylogin will be invoked for each user at 
login time. Thereafter secure RPC commands and programs can be used in the 
same way ordinary commands and programs are used. 



NOTE 



Every machine that allows use of secure RPC is a client machine, even if it 
is also a master or slave server. 



One of the secure RPC commands, chkey, allows users who are logged onto 
only the master server machine to change their secure RPC passwords. 

The .profile files of secure RPC users should be set up to call keylogout 
automatically at the end of a terminal session. For example: 



# .profile code fragment 
trap ^*key logout** 0 



RPC Administration 



10-7 



Secure RPC Overview 



A secure RPG user should always execute keylogout before logging off 
™v.j..™, the system. Failure to do so Is a serious security infraction. 



[See sh(l) for details on use of trap for executing commands at the end of a 
terminal session.] 



NOTE 



The presence of secure RPC has no effect on remote programs that do not 
use the secure protocol. Such programs work normally, whether or not the 
user is also a secure RPC user. 



RPC Domains 

All machines using secure RPC must have a secure RPC domain name. One 
machine per domain acts as master server for the domain. The 
domainname(lM) command is used to set a machine's domain name. The 
machine's SRPC_DOMAIN tunable should also be set to the secure RPC domain 
name. Otherwise, the name is forgotten across reboots. 

Secure RPC identifies users using a triple (operating system, uid, domain). Thus, 
users may have multiple registrations with RPC, provided all such triples are 
unique. For example, a user may belong to more than one domain, with operat- 
ing system and uid identical for each. 

By default, master servers know about users in their own domain. However, 
master servers may export their /domainkeys directories to other master 
servers to acquire information about users in other domains. If those other mas- 
ter servers have an /etc/masters file listing the local master server, they will 
periodically mount the local master's /domainkeys directory and copy their 
domain key data to a file named /domainkeys /masf^r_X (path as seen by the 
local master) where master J^ is the secure RPC domain name of the other mas- 
ter server. 

Given this information, the local master server can periodically update its own 
/etc/publickey file to include key information records from files in 
/domainkeys. 
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In general, administering secure RPC is accomplished as follows: 

1 . A domain name is chosen (for multiple domains, more than one domain 
name is chosen). Secure RPC domain names are set on participating 
machines, using the domainname(lM) command, and the SRPC_DOMAIN 
tunable is set to the secure RPC domain name. 

2. For each user or host to be allowed access to secure RPC services, domain 
master machine administrators add entries to their master 
/etc/publickey file. 

3. keyserv and YP daemons are started. 

4. Administrators start keyserv, either manually or by means of a boot- 
time script. 

5. Administrators of client machines mount the master (or a slave) 
/etc/publickey file and link it as their local /etc/publickey file. 
They remove the comment character that has commented out the keylo- 
gin command from their machine's /etc/profile and they direct their 
secure RPC users to add a trap to their $HOME/ .profile so that keylo- 
gout will be called when their sessions end. 

The following sections detail this procedure. 



mm: 



When slave servers are in use, master servers may have clients as well as 
slaves. 



Establishing Secure RPC Domains 

For many networked systems, a single secure RPC domain will suffice. 
Administrators are notified of the domain name, and they use the 
domainname(lM) command to establish that name as the secure RPC domain 
name for their machine. For example, to set the a machine's domain name to 
research: 
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For networked systems having multiple domains, the process is the same, except 
that two or more different domains will be in use in the network. 

Administrators should also set their machine's SRPC_DOMAIN tunable to their 
secure RPC domain name, as described in 'The /etc/master .d/kernel File'' 
section, above. If this is not done, the domain name will be forgotten across 
reboots. 

A machine can be part of only one domain at any given time. The decision to 
use single or multiple domains depends on need. In general, the advantages of 
multiple domains include: 

■ Duplicate operating system/user ID pairs can be using secure RPC (pro- 
vided they are in different domains). 

■ Access to secure RPC programs can be made selective, if some programs 
are not available to all domains. 

The primary advantage of using a single domain is simplified administration. 



Master /etc/publickey File 

The /etc/publickey file is a database of public/secret key pairs. The file 
contains pairs for users and hosts authorized to use secure RPC. Remote pro- 
cedures that use the DES authentication protocol (built into the RPC package) 
expect to find public/secret key pairs (for the processes that call them) in 
/etc/publickey. A system administrator must therefore add an entry to 
/etc/publickey for each user/ host to be granted access to secure RPC 
resources. A single /etc/publickey file (on a master server or on a collection 
of master and slave servers) is used and shared over the network by machines 
having access to the file. 
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] Secure RPC programs are not required to be iiosted by tlie same macliine 
NOTE that iiosts the master /etc/publickey file. The master 

/etc/publickey machine is not necessariiy the server for any of the 

secure RPC application programs or commands. 



Adding RPC Users with the newlcey Command 

On the domain master server machine (only), the system administrator grants a 
user or host access to secure RPC in that domain by adding an entry to the 
/etc/publickey file. This is accomplished using the newkey(lM) command. 



NOTE 



The newkey Command must be executed on the master sender machine by 
a user with root privHeges. Furthermore, prior to using newkey, the 
machine's secure RPC domain name must have been set. 



For example, to add an entry for the user alice the system administrator 
would enter the following on the master server: 



master! newlcey ~i2 allce 
passMord; <pas^ord><cr> 
Be-6nt6r newi i>a5dwd: <^p(mt»Qrd> <cr> 



The -u option signifies that alice is a user ID. The domain field for this entry 
is the domain of the master server on which this command is executed. This is 
the only way that user alice can get access to this particular secure RPC 
domain. 

The newkey command can also be used with the -h option to give access to 
hosts, i.e., to root users on hosts on the network: 



master* newkey -h client 
paaaword: <password><cr> 
Re'-enter new passvfcS: <pa9Siword> <pr> 
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Within the domain of secure RPC users having entries in a master 
/etc/publickey file, all user names and IDs must be unique. The -h option 
is provided to allow more than one root user to have access to secure RPC. 
Because root users on different machines have the same name and ID, it would 
be impossible for more than one of them to be a secure RPC user. The -h 
option solves this problem, allowing root users to use their unique machine 
name and address as a user name and ID for RPC purposes. 



Network Passwords and the chkey Command 

If using the YP service, client users should be notified of their passwords when 
they are given access to secure RPC. Their .profile files should be modified 
to execute keylogout when they log off. 

Users are prompted for their secure RPC passwords when keylogin is exe- 
cuted by /etc/profile. After gaining access, secure RPC users logged onto 
the master server machine may invoke ttie chkey command to assign them- 
selves a different secret password. 

For example, a user can set up a password as follows: 



ina5ter$ chkey 

Ifew password: <pa&smt^<Cf> 
Be-^t^r new passwi;}? <^pi»!^So(i^rd> <ct> 



Users logged onto client machines and on slave server machines canriot 
NOTE change their passwords in this way. Users should login to their master 
• server to change their network password. 
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Troubleshooting Note 

If all administration procedures have been performed correctly and trouble 
occurs, suspect that an RPC server daemon process (in particular, rpcbind) 
may not have been started, may have died, or may have been killed. 
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This chapter explains how to administer the YP distributed network lookup ser- 
vice. Information in the chapter includes: 

■ The YP environment 

■ Setting up YP servers 

■ Setting up a YP client 

■ Creating and updating maps 

■ YP-related commands 

■ Fixing YP problems 



What is YP? 

YP is a distributed name service designed to meet the administrative needs of 
large, diverse, and evolving computing communities. It is a mechanism for 
identifying and locating objects and resources accessible to the community. It 
provides a uniform, network-vdde storage and retrieval method that is both 
protocol- and media- independent. 

By running the YP service, the system administrator can distribute administra- 
tive databases (maps) among a variety of machines and can update those data- 
bases from a centralized location in an automatic and reliable fashion, ensuring 
that all clients share in the same databases in a consistent manner throughout 
the network. Furthermore, the use of the YP "publickey'' map permits running 
secure RFC and secure NFS across the network of maqhines. 

The YP Elements 

The YP service is composed of the following elements: 

■ domains 

■ maps 

■ daemons: 
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□ ypserv — server process 

□ ypbind — binding process 

□ ypupdated — server for changing map entries 

■ utilities: 

□ ypcat — lists data in a map 

□ ypwhich — lists name of YP server 

□ ypnatch — finds a key in a map 

□ ypinit — builds and installs a YP database, or initializes a client 

□ yppoll — gets protocol version from server 

□ yppush — propagates data from master to slave YP server 

□ ypset — sets binding to a particular server 

□ ypxf r — transfers data from master to slave YP server 

□ makedbm — creates dbm file for a YP map 



The YP Environment 

YP service is based on information contained in YP maps. Maps are non- ASCII 
administrative files, which usually derive from ASCII files traditionally found in 
the /etc directory. Each YP map has a mapname used by programs to access 
it. On a network running YP, at least one YP server per domain maintains a set 
of YP maps for other hosts in the domain to query. 

The service is mediated by the daemons ypserv and ypbind, and updates are 
facilitated by the daemon ypupdated. 
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The YP Domain 

A YP domain is an arbitrary name that designates which machines will make 
use of a common set of maps. Maps for each domain are located in separate 
directories, /var/yp/ domainmme, on the YP server (see "YP Servers"). For 
example, the maps for machines that belong to the domain accounting will be 
located in the directory /var/yp/accounting on their corresponding YP server. 

No restrictions are placed on whether a machine can belong to a given domain. 
Assignment to a domain is done at the local level of each machine by the sys- 
tem administrator logged in as superuser; it can be done in any of the following 
three ways: modify /etc/rc2.d/s75ppc; modify /etc/master . d/kernel; or by 
entering the command 



# domalnname name 




where name is the name of the domain to which you want the machine to 
belong. 

YP Machine Types 

There are three types of YP machines: 

■ master server 

■ slave server 

■ client 

Any machine can be a YP client, but only machines with disks should be YP 
servers, either master or slave. Servers are generally also clients. 

YP Servers 

By definition, a YP server is a machine with a disk storing a set of YP maps that 
it makes available to network hosts. The YP server does not have to be the 
same machine as the file server, unless, of course, it is the only machine on the 
network with a disk. 
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YP servers come in two varieties, master and slave. The machine designated as 
YP master server contains the master set of maps that are updated as necessary. 
If you have only one YP server on your network, designate it as the master 
server. Otherwise, designate the machine you think will be best able to pro- 
pagate YP updates with the least performance degradation. 

You can designate additional YP servers on your network as slave servers. A 
slave server has a complete copy of the master's set of YP maps: Whenever the 
master server's maps are updated, it propagates the updates among the slave 
servers. The existence of slave servers allows the system administrator to distri- 
bute evenly the load implied in answering YP requests. The following diagram 
is a stylized representation of the relationship between master, slaves and 
clients: 




A server may be a master in regard to one map, and a slave in regard to 
another. However, randomly assigning maps to YP servers can cause a great 
deal of administrative confusion. You are strongly urged to make a single server 
the master for all the maps you create within a single domain. The examples in 
this chapter assume that one server is the master for all maps in the domain. 
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YP Clients 

YP clients run prcx:esses that request data from maps on the servers. Clients do 
not care which server is the master in a given domain, since all YP servers have 
the same information. The distinction between master and slave server only 
applies to where you make the updates. 

YP Binding 

YP clients get information from the YP server through the binding process. 
Here is what happens during YP binding: 

1 . A program running on the client (that is, a client process) and needing 
information that is normally provided by a YP map, asks ypbind for the 
name of a server. 

2. ypbind looks in the file /var/yp/binding/domflmnam^/ypservers to 
get a list of the servers for the domain (see "Establishing the Domain" 
later in this chapter). 

3. ypbind initiates binding to the first server on the list. If the server does 
not respond, it tries the next, and so on until it finds a server or exhausts 
the list. 

4. ypbind tells the client process which server to talk to. The client then 
forwards the request directly to the server. 

5. The ypserv daemon on the YP server handles the request by consulting 
the appropriate map. 

6. ypserv then sends the requested information back to the client. 

The binding between a client and a server can change with the network's load 
as the service tries to compensate for current activity; that is, a client may get 
information from one server at one time and from another server at a different 
time. 

To find out which YP server is currently providing service to a client, use the 
ypwhich command 
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V 

where hostname is the name of the client. If no hostname is mentioned, 
ypwhich defaults to the local host (the machine on which the conunand is 
entered). 

YP Maps 

YP maps are one type of implementation of System V Release 4.0 administrative 
databases. (The other implementation is the ASCII files generally found in the 
/etc directory.) Information in YP maps is organized in a format similar to 
System V Release 4.0 dbm files. The manual pages for ypf iles(5) and dbm(3) 
completely explain the dbm file format. Input to makedbm must be in the form 
of key/value pairs, where key is the first word of each line and value is whatever 
follows in that line. The input can be from a file or from standard input (as 
when modified through a script; see below, "Making the Maps"). After passing 
through makedbm the data is collected in non-ASCII form in two files, 
mapname . dir and mapname . pag, both in the /var /yp/domainmtne directory. 

The pairs of keys and values are preserved in the YP maps, so programs can use 
the keys to look up the values. 

The System V Release 4.0 package includes a default YP map, 
publickey . byname, and a default makefile for that map. 
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Implementation of the YP service consists of the following steps: 

1 . Establishing the domain(s) for your machines 

2. Writing or preparing the maps in ASCII form 

3. Running the ASCII files through roakedbm 

4. Setting the master server 

5. Starting daemons in the master server 

6. Setting the slave server(s) 

7. Starting daemons in the slave server(s) 

8. Initializing the clients 

The following sections will describe each of these steps. 

Establishing tlie Domain 

Before you configure machines as YP servers or clients, you must prepare the 
YP domain by: 

■ Giving it a name. 

A domain name can be up to 256 characters long. However, because your 
/var/yp directory may reside in an s5 file system, and the domain name 
you select may be longer than the 14-character limit that s5 imposes on 
filenames, the program ypinit makes a shortened domain name and 
stores it in the /var/yp/aliases file. The name of the database direc- 
tory /var /yp/domainname will correspond to the shortened alias for the 
domain name. 

■ Designating which machines will serve or be served by the YP domain. 

Once you have chosen a domain name, make a list of network hosts that 
will give or receive YP service within that domain. 

■ Determining which machine should be master server (you can always 
change this at a later date). 



The YP Service 



11-7 



Implementing the YP Service 



■ Listing which hosts on the network, if any, are to be slave servers. 

■ Finally, listing all the hosts that are to be YP clients. 

You will probably want all hosts in your network's administrative domain to 
receive YP services, although this is not strictly necessary. If this is the case, 
give the YP domain the same name as the network administrative domain. 

Log in as superuser to all servers, whether master or slave(s), and all clients of 
the YP domain. Enter the command 

( 

# dannainnarae nam& 

where name is the name of the domain. 

The above is a temporary measure; edit the file in /etc/rc2 .d/s75rpc that 
initiates YP service or edit /etc/master . d/kernel. 

f 

dctnainname mm^ 

V 

where name is the name of the domain. 



Preparing the Maps 

System V Release 4.0 enables a site to use public key encr5q>tion as one of the 
methods for providing secure networking. If you are planning on running 
secure RPC or secure NFS, you may use YP to administer the 
/etc/publickey file. 
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The publickey Map 

This file consists of three fields in the following format: 




name vfifr publickey ; v^sBcretl 



J 



where user name may be the name of a user or of a machine, user public hey is 
that key in hexadecimal notation, and user secret key is that key also in hexade- 
cimal notation. 

Since nobody expects you to be conversant in hexadecimal notation, the pro- 
gram newkey is provided to make things easier. Simply become superuser at 
the master server and invoke newkey for a given user by typing 



# newkey mtmamR 



J 



or for the superuser on a given host machine by typing the following: 



# netricey -^h hostname 



At the prompt enter the appropriate secure RFC or network password. The 
program will then create a new public/secret key pair in /etc/publickey, 
encrypted with the secure RFC or network password of the given user. 

Users can later modify their own entries, or can even create them, by using the 
program chkey. The user simply types: 

$ chkey 

J 
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and then responds to prompts from the command. A t)T>ical chkey session 
would look like this: 



Generating new key for usemame 




Pa33worcl; ttser enters password 




Senditjg k«y cha^gre irequedt to «n?^r.*. 




Done^ 






willow? 







Note that in order for newkey and chkey to run properly, the daemon ypup- 
dated must be running in the master server. If it is not running at this point, 
enter the following: 



: :# : /usr/lib/netsvc/yp/ypupdated 



You must also make sure that the appropriate file in /etc/rc? . d contains the 
lines 



if I -f /uer/iib/net«vc/yp/ypupciate(S -a /vair/yp/Mcii«innaine» ] 

/usr/lib/net3vc/yp/ypupdatect 

(edio \c ■* ypupdatM') >/dev/con3oXe 



The ypupdated daemon consults the file /var/yp/updaters for information 
about which maps should be updated and how to go about it. In the case of the 
publickey map, changes to /etc/publickey affected through newkey or 
chkey are mediated by /usr/sbin/udpublickey. 
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Other Maps 

Other maps do not need the assistance of special programs for their creation or 
modification. For instance, if you are planning on having distributed auto- 
mounter files, all you have to do is write the automounter files as they would 
reside in a machine's /etc directory. (For more information on the auto- 
mounter, see the chapter on the automounter in the "Network File System 
Administrator's Guide" in the Network User's and Administrator's Guide.) 

A typical auto. master file would contain 



♦Mount-point Hap Mount-^lona 

/net -hosts 

/heme /etc/auto, home -rw* intr,, secure 

/- /etc/auto, direct -ro,jLntr 



A typical auto . home map would contain the following: 



Ikey mount-<^tlons location 
willow willow ; /home/willow 

cypress cypress : /home/c^resa 

poplar poplar: /home/poplar ^ 

pine pine: /export /pine 

apple apple : /export/hotne 

ivy ivy; /home/ivy 

peach --rw^noiiuid peach :/export/hotive 



The following would be a t5^ical /etc/auto . direct map: 
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^ 










/uSX/ JrOCoJ. \ 

/bin -lo, soft 

/usr/game^ -ro, soft 
/usr/spool/news -ro, soft 
/iist/f^amfe -TO, soft 


lvyt/6S|iort/local/smi3 \ 
ivyt/ea5x>rt/Xocal/slMU» \ 
ivy i /expoxt/Xoca 
pakr/usr/man \ 
rose;/usr/inaji \ 
willo>r: /usr/inan 
peach : /usr/garaes 
pine: /ust/spooX/tiews 
xedvKxxi:/usr/frasnel,5 \ 
balsa ; /export / f 4W»e 








^ 









A full explanation of what these files mean can be found in the chapter on the 
automounter in the Network User's and Administrato/s Guide. 

Note that these files are all in the directory /etc. These are not the maps, these 
are the files that you will use in order to make the maps. 

The automounter recognizes the notation + at the beginning of a line as an indi- 
cation to consult the corresponding YP map; this notation is permissible in a 
client's file in the /etc directory. 



Making the Maps 

Your next step, after creating the maps, is to convert these ASCII files into the 
non- ASCII files in dbm format that the YP service expects. The prescribed 
method is to use the inake(l) program through a permanent Makefile. 

The Default Makefile 

A makefile is provided in the directory /var/yp. It contains the commands 
needed to transform /etc/publickey into the desired dbm format and is simi- 
lar to the following: 



11-12 



Programmer's Guide: Networking Interfaces 



implementing the YP Service 



# PROPRIETARY NOTICE <Coi*itt©d> 

4 This 9Qurce code is unpublished proprietary information 

# coiwtit^ting^ or derived under license froro ATAT'a System V, 

# In addition, portions of such source code were derived from Berkeley 
#4.3 BSD under license from the Regents of the University of 

# California. 

# 
# 

# 

# 
# 
# 



Copyright Notice 

Notice of copyright on this source code product does not Indicate 
publication k 

(c) 1986, 1987 , 1 988 . 1989 Sun Microsystems, Inc 
(C) 1983*1984,1985/1986,1987,1988,1989 
All rights reserved. 

Set the following variable to '•-b*' to have yp servers use the domain 
xesolver for hosts not in the current domain. 



DIR «/etc 

" Momainn^ne^ 
NWCrSH »- 
YPDIR«/usr/sbin 
YPI^IR«/var/yp 
yppUSH«§ <YPDIR) /yppush 
HM^EDBM**$ <YPDIR> /makedbm 
!«CNETID«$ /mktietid 



all: 



$ (YPDBDIR) /$ (DC»!> /publickey .byname; 



$ ( YPDBDIR) /$ (DOM) /publickey . byname : $ (DIR) /publickey 
sed '♦/'^#/d" < $ (DIR) /publickey I \ 

$(MRKEDBM) - $ (YPDBDIR) /$ (DOM) /publickey . byname; 
echo *^updated publickey"; 
if { ! $(NOPt)SH) ]; then \ 

$(YPPDSH) publickey .byname; \ 

echo "piished publickey**; \ 

eilse \ 
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This makefile first creates an entry in /var/yp/aliases which translates the 
mapname into a shorter name to be used for the dbm file name (this is done to 
accomodate the 14-character limitation that s5 file systems impose on file 
names.) Then it eliminates all lines in /etc/publickey that start with a # 
(that is, comment lines) and passes the rest to makedbm. makedbm creates the 
files publickey . pag and publickey . dir. Both of these files are in the 
directory /var /yp/domain.mme. The makefile then touches a file called 
publickey .time (to keep track of updates) and calls the yppush program, if 
applicable, to propagate the changes to all slave servers. 

It is inappropriate to call make until you have set the slave servers. 

Modifying the Malcefile 

In order for the makefile to work on the automounter files (or any other files) 
that you wish to propagate through YP, the following modifications must be 
made: 

1 . Modify the line that says 

^ ^XX: pubXlc k^y 

to say the following: 

^ ^aXX; pubXick^y auto» direct auto.hcifte auto.nvaater 

The order is not relevant. 

2. Add the following lines at the end of the makefile: 

auto .direct : auto, dia?6ct .time 
auto. home: auto.homa.tinte 
auto.waat^; auto, master, time 

V 





11-14 



Programmer's Guide: Networlcing Interfaces 



Implementing the YP Service 



3. Add the following entry for the auto . direct map in the middle of the 
file, after the entry for publickey .time and before the line that reads 
publickey : publickey . time: 

aut;<>4 direct < t Ime : $ /publickey 

-if ( -f $(PiJM/avto. direct }s tJ)e» \ 

dtihd atltd.ditBct .byname ^$(AXit^) |)ublidc^y, byname^ » H^tP^Xm: \ 
9Qrt $(ALIASFII£} | uniq > kypalia999; ^ypalias^s $ (ALIASFHE) ; \ 
for 1 in ${DOM); do \ 
ddd '^/•^t/d" \ 

"Z'^+Zd" $(DIR> /auto .direct I \ 
$(MZ«EaDiBM) - $(ypi»DIR)/»$ (ALIAS) \ 

^ $$iV'$ (ALIAS) aiito.direct.bynaine\' \ 

done; \ 

touch auto. direct, time; \ 
echo ^updated autO, direct**; \ 
if i I $(NOPtJSH) ]; then \ 

$<XPI>OSH> auto, direct. byname; \ 

echo ''pushed auto. direct"; \ 
el3e \ 

wmmBmmm^ 

eXae \ 

echo •♦couldn't find ^(Ea:R)/auto.dlrBcf; \ 




Create similar entries for auto. home and auto. master. 



Setting the Master Server 

The program that helps you establish the n\aster and slave servers, and permits 
the initial mapping of ASCII files and their propagation, is 
/usr/lib/netsvc/yp/ypinit. 

You use the shell script ypinit to build a fresh set of YP maps on the master 
server in the following way: 
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Bring the machine that is going to be your master server to single-user 
mode, or to a mode that is not defined as running the YP service, and log 
in as superuser. 

Type 



# cd /var/yp 

I /usr/lib/netsvc/yp/yp±nlt 



3. ypinit prompts for a list of other hosts that are to become YP servers. 
Enter the name of the server you are working on and the names of all 
other YP servers. 

4. ypinit asks whether you want the procedure to die at the first non-fatal 
error or to continue despite non-fatal errors. 

If you choose the first option, ypinit will exit at the first problem; you 
can then fix the problem and restart ypinit . This is recommended if 
you are running ypinit for the first time. If you prefer to continue, you 
can try to fix by hand all problems that may occur, then restart ypinit . 

Once ypinit has constructed the list of servers, it calls up make(l). This 
program uses the instructions contained in the makefile (either the default 
one or the one you modified) located in /var/yp. It cleans all comment 
lines from the files you designated and runs makedbm on them, creating 
the appropriate pairs of maps and establishing the name of the master 
server for each map. 



NOTE 



For security reasons, you may want to restrict access to the master YP 
server. 
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Starting Daemons in the Master Server 

The success of the remaining procedures depends on the presence of the 
ypserv daemon in the master server. 

If your master server is still in single-user mode or at an inappropriate 
run-level, bring it to the run-level that is defined as allowing YP services to run. 
This entails having the following or similar lines in the appropriate file in the 
/etc/rc? . d directory: 





































f 









/u»r/lib/netsvc/yp/ypserv 

(«chp \<5 ' ypserv') >/dBv/console 



fi 

if t -d /var/yp 1; then 



/Tisr/lib/netsvc/yp/ypbind 

(echo \c ' ypbind') >/de!V/console 



£1 



Once you have made sure that these lines are in the file, and that there is an 
executable file called /usr /lib/net svc/yp/ypserv and a directory under 
/var/yp named after the domain name, log in as root and enter the command 



# Init # 



where # is at least run-level 2. 
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Setting Slave Servers 

Your network can have one or more YP slave servers. Before actually running 
ypinit to create the slave servers, you should take several precautions. 

The domain name for each YP slave must be the same as the domain name of 
the YP master server. Use the domainname command on each YP slave to 
make sure it is consistent with the master server. Make any necessary changes 
to the domain name, as described in the previous section, "Setting Up the YP 
Domain." Do not forget to set each slave server's host name. 

Make sure that the network is working properly before you set up a slave YP 
server. In particular, check that you can use rep to send files from the master 
YP server to YP slaves. If you cannot, follow the procedures outlined in the 
Network User's and Administrator's Guide to permit the use of rep. 

Now you are ready to create a new slave server. 

1 . Log in to each slave server as superuser and bring the slave server to a 
run-level, preferably single user, that does not imply running the YP ser- 
vice, ypserv must not be running. 

2. Change directory to /var/yp. 

3. Type the following: 

/uar/ltb/mtsvc/yp/ypinit -c 

Enter the names of the YP servers in order of preference; that is, enter 
first the names of the servers that are physically closest to the machine in 
the network. If the client is also a server, enter its name first. This initial- 
izes the client and estabhshes its servers for binding. 
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4. Type the following: 



# /uar/llb/net5fvc/yp/ypbincl 



5. Type 

^ 



# /i«5r/llb/net»vo/yp/ypinlt -3 master 



J 



where master is the host name of the existing YP master server. Ideally, 
the named host is the master server, but it can be any host with a stable 
set of YP maps, such as another slave server. 

ypinit will not prompt you for a list of other servers, as it does when 
you create the master server, nor will it run make again. However, it will 
stop executing if you have not used ypinit -c to initialize the list of 
servers, and it lets you choose whether or not to halt at the first non-fatal 
error, ypinit then calls the program ypxf r, which transfers a copy of 
the master's YP map set to the slave server's /var /yp/domainname direc- 
tory. 

When ypinit terminates in each slave, make sure that the ASCII files in 
the /etc directory direct whichever program reads them to the YP maps, 
thus ensuring homogeneity across the network. For instance, if you have 
added the maps auto . master, auto . home, and auto . direct to the 
YP maps, make a copy of each of these files in each slave by typing 



r 



# qp /etc/auto. hone /etc/auto. hom^- 



or the following: 
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/etc/auto, ho«»ei 

































































Note that in the particular case of the automounter, if the invocation does 
not contain the -m option, then it Will automatically look for a YP 
auto. master map. You can therefore move the auto. master file into 
another file: 



Edit the original files (not those with the - or . old extension) and make 
them refer to the YP maps. For instance, the file /etc/auto . direct 
should contain, as its last line, something similar to the following: 



Thus, whenever the automounter reads this file, it will consult the YP 
auto . direct map upon reaching this line. 

9. The preceding procedures ensure that processes on the slave server actu- 
ally use the YP services, rather than files in the local /etc. In this way, 
you ensure that the YP slave server is also a YP client. 

10. Back up copies of the edited files. For instance, you might type the fol- 
lowing: 



I cp /etc/auto » direct /etc/auto.dixect+ 
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Repeat the procedures above for each machine you want configured as a YP 
slave server. 



Starting Slave Server Daemons 

The procedure for starting the YP daemons in a slave server is exactly the same 
as that used for starting the YP daemons in the master server, as explained in 
"Starting Daemons in the Master Server." 



Setting Up a YP Client 

To estabUsh a machine as a YP client, do the following: 

1 . Edit the client's local files, as you did for the local files in the slave 
servers, so that processes consulting those files are sent to the YP maps. 



Run 





^ — 


































/uar/lib/netsvc/yp/ypinlt -c 













































to initialize the client. 

Bring the client to the run-level defined as permitting the running of YP 

services, after making sure that the appropriate file in the 

/etc/rc2 .d/s75rpc directory contains lines similar to the following: 



it i -d /var/yp J; therx 

/usr/lib/netsvc/yp/ypblnd 

(echo \c ' ypblnd') ^AJev/consde 



The YP Service 



11-21 



Implementing the YP Service 



4. Type 

c ^ 

# ps --ef f grep ypbind 

v_ 

to confirm that /usr/lib/netsvc/yp/ypbind is running. 

With the relevant files in /etc abbreviated and ypbind running, the processes 
on the machine will be clients of the YP servers. 

At this point, you must have configured a YP server on the network and have 
given that server's name to ypinit. Otherwise, processes on the client hang if 
no YP server is available while ypbind is running. 
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This section describes how to maintain the maps of an existing YP domain. 
Subjects discussed include: 

■ Updating YP maps 

■ Propagating a YP map 

■ Adding maps to an additional YP server 

■ Moving the master map set to a new server 



Updating Existing Maps 

After you have installed YP, you will discover that some maps require frequent 
updating while others never need to change. For example, the publickey map 
may change frequently on a large company's network. On the other hand, the 
auto. master map probably will change little, if at all. 

When you need to update a map, you can use one of two updating procedures, 
depending on whether the map is standard or non-standard. A standard map is 
a map in the default set created by ypinit from the network databases. Non- 
standard maps may be any of the following: 

■ A map included with an application purchased from a vendor 

■ A map created specifically for your site 

■ A map existing in a form other than ASCII 

The following text explains how to use various updating tools. In practice, you 
probably will use them only if you add non-standard maps or change the set of 
YP servers after the system is up and running. 

Modifying Standard Maps 

Use the following procedure for updating all standard maps: 

1 . Become superuser on the master server. (Always modify YP maps on the 
master server.) 
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2. Edit the file in /etc that has the same name as the map you want to 
change. 

3. Type the following: 



« itiak^ mapmmtt 



The make command will then update your map according to the changes 
you made in its corresponding file. It will also propagate it among the 
servers (see the section "Propagating a YP Map'' for more information). 



Do not use this procedure with the publickey map. Instead, use the new- 
key and chkey commands, as described in "Preparing the Maps." 



Creating and Modifying Non-Standard Maps 

To update a non-standard map, you edit its corresponding ASCII file. Then you 
rebuild the updated map using the /usr/sbin/nvakedbm command. [The 
n\akedbm(lM) manual page fully describes this command.] If the map has an 
entry in the /var/yp /Makefile, simply run make. If the map does not have 
an entry, try to create one following the instructions in "Making the Maps," 
above. Using make is the preferred method; otherwise, you will have to use 
makedbm by hand. 

There are two different methods for using makedbm: 

■ Redirect the command's output to a temporary file, modify the file, then 
use the modified file as input to makedbm. 

■ Have the output of makedbm operated on within a pipeline that feeds into 
makedbm again directly. This is appropriate if you can update the 
disassembled map with either awk, sed, or a cat append. 
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You can use either of two possible procedures for creating new maps. The first 
uses an existing ASCII file as input; the second uses standard input. 

In all cases, if /var/yp resides in an s5 file system, you have to create an alias 
for the map to deal with the 14-character limitation for file names (which, in the 
case of map names, is actually an 8-character limitation because of the suffixes 
that makedbm creates). To do this, change directory to /var/yp and enter the 
command: 



echo mapname Vus3r/lll>/netsvc/yp/ypaXia8 mapname'' » aliases 



Updating lUiaps Buiit from Existing ASCil Files 

Assume that an ASCII file /var/yp/mymap . asc was created with an editor or 
a shell script on the YP master. You want to create a YP map from this file, and 
locate it in the home_domain subdirectory. To do this, you type the following 
on the master server: 



r 



4 ad /var/yp 
: # : : : /usr/sbin/inalcadbro: roy^ 



The mymap map now exists in the directory home^domain. 

Adding entries to mymap is simple. First, you must modify the ASCII file 
mymap .asc. (If you modify the actual dbm files without modif)ang the 
corresponding ASCII file, the modifications are lost.) Type the following: 



# cd /var/yp 

# <edit ni;^nap,a3c> 



:# : : : /uar/abln/inakadbin : m^n^ ; hoinexdoRiain/inyinap. 



When you finish updating the map, propagate it to the slave servers, as 
described in the section "Propagating a YP Map." 
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Updating Maps Built from Standard Input 

When no original ASCII file exists, create the YP map from the keyboard by 
typing input to makedbm, as shown below: 



ypraaster# od /var/yp 

ypmadter# /usr/aibln/wdkedbm - hoii«6jJoittaltt/»p>^ 
keyl valuel 
key2 vaXi2e2 
key3 vdXiie3 
<ctl D> 



If later you need to modify a map that is not based on an existing file, you can 
use makedbm -u to disassemble the map and create a temporary ASQI inter- 
mediate file. You type the following: 



$ /usr/sbin/roakedfam home jioroain/myroap > mymap.temp 



The resulting temporary file mymap . temp has one entry per line. You can edit 
it as needed, using your preferred editing tools. 

To update the map, you give the name of the modified temporary file to mak- 
edbm as follows: 



$ /usr/sbin/makedbm irr/map.temp hanejdowain/myinap 
$ zm rnymapttiGnip 



When makedbm finishes, propagate the map to the slave servers, as described in 
the section 'Tropagating a YP Map." 

The preceding paragraphs explained how to use some tools. In reality, almost 
everything you have to do can be done by ypinit and /var/yp/Makef ile, 
unless you add non-standard maps to the database or change the set of YP 
servers after the system is already up and running. 
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Whether you use the makefile in /var/yp or some other procedure, a new pair 
of well-formed dbm files must end up in the domain directory on the master YP 
server. 



Propagating a YP Map 

When you propagate a YP map, you move it from place to place — ^most often 
from the master to all YP slave servers. Initially ypinit propagates the maps 
from master to slaves, as described previously. From then on, you must 
transfer updated maps from master to slaves by running the ypxf r command. 
You can run ypxf r three different ways: periodically through the root cron- 
tab file; by the ypserv daemon; and interactively on the command line. 

ypxf r handles map transference in tandem with the yppush program, 
yppush should always be run from the master server. The makefile in the 
/var/yp directory automatically runs yppush after you change the master set 
of maps. 

yppush's function is to copy, or "push,'' a new version of a YP map from the 
YP master to the slave(s). After making a list of YP servers from the 
ypservers map built by ypinit, yppush contacts each slave server in the 
list and sends it a "transfer map" request. When the request is acknowledged 
by the slave, the ypxf r program transfers the new map to the slave. 

Using crontab with ypxfr 

Maps have differing rates of change. For instance, auto. master may not 
change for months at a time, but publickey may change several times a day in 
a large organization. When you schedule map transference through the cron- 
tab command, you can designate the intervals at which individual maps are to 
be propagated. 

To run ypxfr periodically fit a rate appropriate for your n\ap set, edit root's 
crontab file on each slave server and put the appropriate ypxfr entries in it 
[see the manual page for crontab(l)]. ypxfr contacts the master server and 
transfers the map only if the master's copy is more recent than the local copy. 
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Using Shell Scripts with ypxfr 

As an alternative to creating separate crontab entries for each map, you may 
prefer to have root's crontab periodically run shell scripts that update the 
maps. You can easily modify these shell scripts to fit your site's requirements 
or replace them. Here is an example shell script: 



#2 /blA/sh 

llilllllllllillillilll 

# yi»tfr Xper<Jay.ah - Do dally yp mp <2heck/upddt6s 

# set 

ypxfr publickey.]:r/name: 
ypxfr ai3to^<aiJ?ect 
ypxfr ypsetvers 



This shell script will update once per day the maps mentioned in it, as long as 
root's crontab executes it once a day (preferably at times of lov^ network 
load). You can also have scripts update maps once a week, once a month, once 
every hour, and so on, but be aware of the performance degradation implied in 
propagating the maps. 

Run the same shell scripts through root's crontab on each slave server 
configured for the YP domain. Alter the exact time of execution from one 
server to another to avoid bogging down the master. 

If you want to transfer the map from a particular slave server, use the -h host 
option of ypxfr within the shell script. The syntax of the commands you put 
in the script is 



^ ^/usr/lUi^/netgvc/yp/ypxfr host mapname 

where host is the name of the server with the maps you want to transfer, and 
mapname is the name of the requested map. If you use the -h option without 
specifying host, ypxfr will try to get the map from the master server. 
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You can use the -s domain option to transfer maps from another domain to 
your local domain. These maps should be essentially the same across domains. 

Directly Invoking ypxfr 

The third method of invoking ypxfr is to run it as a command. Typically, you 
do this only in exceptional situations - for example, when setting up a tem- 
porary YP server to create a test environment, or when trying to make a YP 
server that has been out of service consistent with the other servers. 

Logging ypxfr's Activities 

ypxfr 's transfer attempts and the results can be captured in a log file. If a file 
called /var/yp/ypxf r . log exists, results are appended to it. No attempt to 
limit the size of the log file is made. To prevent it from growing indefinitely, 
empty it from time to time by entering 



# cp /var/yp/ypxf r. log /var/yp/ypxfr.log»old 

# cat /dev/null > /var/yp/ypacfr.log 



You can have crontab execute these commands once a week. 
To turn off logging, remove the log file. 



Adding New YP Maps to the Makefile 

Adding a new YP map entails getting copies of the map's dbm files into the 
/var/yp/ domain jmme directory on each of the YP servers in the domain. The 
actual mechanism is described above in 'Tropagating a YP Map." This section 
only describes how to update the makefile so that propagation works correctly. 

After deciding which YP server is the master of the map, modify 
/var/yp /Makefile on the master server so that you can conveniently rebuild 
the map. As indicated previously, different servers can be masters of different 
maps. This can, however, lead to administrative confusion, and it is strongly 
recommended that you set only one server as the master of all maps. Actual 
case-by-case modification is too varied to describe here, but typically a human- 
readable ASCII file is filtered through awk, sed, and/or grep to make it 
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suitable for input to makedbm. Refer to the existing /var/yp/Makef ile for 
examples and to the previous section, "Modifying the Makefile." 

Use the mechanisms already in place in /var/yp/Makef ile when deciding 
how to create dependencies that make will recognize; specifically, the use of 
. time files allows you to see when the makefile was last run for the map. 

To get an initial copy of the map, you can have make run yppush on the YP 
master server. The map must be available globally before clients begin to access 
it. 



mm 



If the map is available from some YP servers, but not all, you will encounter 
unpredictable behavior from client programs. 
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After YP is running, you may need to create a YP slave server that you did not 
include in the initial set given to ypinit. The following procedure explains 
how to do this: 

1. Log in to the master server as superuser. 

2. Go to the YP domain directory by typing: 



# cd /v^/^/dmmmjiam 
3. Disassemble ypservers, as follows: 

# /usr/sbln/malcecJisro ypaerwers > /tiap/tempJUe 



makedbm converts ypservers from dbm format to the temporary ASCII 
file /tmp /tempjile. 

4. Edit /tmp/temp Jile using your preferred text editor. Add the new slave 
server's name to the list of servers. Then save and close the file. 

5. Run the makedbm command with temp__f ile as the input file and 
ypservers as the output file. 







^ 




/txtp/iemp JUe yps©rwer« 


J 



Here makedbm converts ypservers back into dbm format. 

6. Verify that the ypservers map is correct (since there is no ASCII file for 
ypservers) by typing the following: 



The YP Service 



11-31 



Adding a New YP Server to the Original Set 



NOTE 



If a host name is not in ypservers, it will not be warned of updates to 
the YP map files. 



Here makedbm will display each entry in ypservers on your screen. 

7. Set up the new slave server's YP domain directory by cop5dng the YP 
map set from the master server. To do this, log in to the new YP slave as 
superuser and run the ypinit command: 



ypslave# cd /var/yp 

yp3lave# ^init ^ 

< mter the list of servers > 

ypslavel /usr/lib/netsvc/yp/ypibind 

yp3lave# /uer/lJJs/n^t^vc/yp/ypinit -3 ypmasier 



When you are finished, complete Steps 5 and 6 in the "Setting Slave 
Servers" section. 



Changing a Map's Master Server 

To change a map's master, you first have to build it on the new YP master. The 
old master's name occurs as a key-value pair in the existing map (this pair is 
inserted automatically by makedbm). Therefore, using the existing copy at the 
new master or transferring a copy to the new master with ypxf r is insufficient. 
You have to reassociate the key with the new master's name. If the map has an 
ASCII source file, you should copy it in its current version to the new master. 
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Here are instructions for remaking a sample YP map called 
jokes .bypunchline. 

1 . Log in to the new master as superuser and type the following: 

2. /var/yp/Makef ile must have an entry for the new map before you 
specify the map to make. If this isn't the case, edit the makefile now (see 
"Making the Maps"). 

3. Type the following: 

^ ^newmasterl make jolceg. bypunchline 

4. If the old master will remain a YP server, r login in to it and edit 
/var/yp/Makef ile. Comment out the section of /var/yp/Makef ile 
that made jokes . bypunchline so that it is no longer made there. 

5. If jokes . bypunchline only exists as a dbm file, remake it on the new 
master by disassembling a copy from any YP server, then running the 
disassembled version through makedbm: 

nefliKrtaaterl od /var/yp 

neumasterl ypcat jokes. bypunchline t\ 

yu3r/3li>in/jnak^cjD5in - rfomawi/ jokes. bypunchline 

V _I J 

Don't forget that jokes .bypunchline should be in the alias file too. 

After making the map on the new master, you must send a copy of it to the 
other slave servers. However, do not use yppush, as the other slaves will try to 
get new copies from the old master, rather than the new one. A typical method 
for circumventing this is to transfer a copy of the inap from the new master 
back to the old master. Become superuser on the old master server and type: 
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V . . 

Now it is safe to run yppush. The remaining slave servers still believe that the 
old master is the current master. They will attempt to get the current version of 
the map from the old master. When they do so, they will get the new map, 
which names the new master as the current master. 

If this method fails, you can try this cumbersome but sure-fire option. Log in as 
superuser on each YP server and execute the ypxf r conuiiand shown above. 
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In addition to maps, YP service also includes specialized daemons, system pro- 
grams, and commands, which are summarized below. 

ypserv Looks up requested information in a map. ypserv is a daemon 

that runs on YP servers with a complete set of maps. At least 
one ypserv daemon must be present on the network for YP 
service to function. 

ypbind Initiates binding, ypbind is the YP binder daemon. It must be 

present on both clients and servers. It initiates binding by 
finding a ypserv process that serves maps within the domain 
of the requesting client, ypserv must run on each YP server, 
ypbind must run on all servers and clients. 

ypinit Automatically creates maps for a YP server from files located in 

/etc. ypinit also constructs the initial maps that are not built 
from files in /etc, such as ypservers. Use ypinit to set up 
the master YP server and the slave YP servers for the first time, 
as well as to initialize all clients. 

make Updates YP maps by reading the Makefile in /var/yp. You 

can use make to update all maps based on the files in /etc or 
to update individual maps. The manual page ypmake(lM) 
describes make functionality for YP. 

makedbm Takes an input file and converts it into dbm . dir and . pag 

files — valid dbm files that YP can use as maps. You can also use 
makedbm -u to "disassemble'' a map, so that you can see the 
key-value pairs that comprise it. 

ypxf r Moves a YP map from one server to another, using YP itself as 

the transport medium. You can run ypxf r interactively, or 
periodically from a crontab file. It is also called by ypserv to 
initiate a transfer. 

yppush Copies a new version of a YP map from the YP master server to 

its slaves. You run it on the master YP server. 

ypset Tells a ypbind process to bind to a named YP server, ypset is 

not for casual use. 
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yppoll Tells which version of a YP map is running on a server that you 

specify. It also lists the master server for the map. 

ypcat Displays the contents of a YP map. 

ypmatch Prints the value for one or more specified keys in a YP map. 

You cannot specify which YP server's version of the map you 
are seeing. 

ypwhich Shows which YP server a client is using at the moment for YP 
services, or, if invoked with the -m mapname option, which YP 
server is master of each of the maps. 

ypupdated Facilitates the updating of YP information. 
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This section explains how to clear problems encountered on networks running 
YP. It has two parts, one covering problems seen on a YP client and another 
covering problems seen on a YP server. 

Debugging a YP Client 

Before trying to debug a YP client, review the first part of the chapter, which 
explains the YP environment. Then look for the subheading in this section that 
best describes your problem. 

Hanging Commands on the Client 

The most common problem of YP clients is for a command to hang and gen- 
erate console messages such as: 



yp: server not responding for domain <dmmmme>. Still trying 




Sometimes many commands begin to hang, even though the system as a whole 
seems normal and you can run new commands. 

The message above indicates that ypbind on the local machine is unable to 
communicate with ypserv in the domain domainmme. This happens when a 
machine running ypserv has crashed or is down or unavailable for any reason. 
It may also occur if the network or YP server is so overloaded that ypserv can- 
not get a response back to the client's ypbind within the timeout period. 

Under these circumstances, every client on the network will experience the same 
or similar problems. The condition is temporary in most cases. The messages 
will usually go away when the YP server reboots and restarts ypserv, or when 
the load on the YP server or network itself decreases. 

However, commands may hang and require direct action to clear them. The fol- 
lowing list describes the causes of such problems and gives suggestions for 
fixing them: 
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■ The YP client has not set, or has incorrectly set, the machine's domain 
name. Clients must use a domain name that the YP servers know. 

■ On the client, type domainname to see which domain name is set. Com- 
pare that with the actual domain name in /var/yp on the YP master 
server. If a machine's domain name is not the same as the server's, the 
machine's domain name entry in its installation scripts is incorrect. Log in 
as superuser, edit the client's installation scripts, and correct the domain- 
name entry. This assures the domain name is correct every time the 
machine boots. Then set domainname manually by typing the following: 

■ If commands still hang, make sure the server is up and running. Check 
other machines on your local network. If several clients also have prob- 
lems, suspect a server problem. Try to find a client machine behaving 
normally, and type the ypwhich command on it. If ypwhich does not 
respond, kill it and go to a terminal on the YP server. Type the following: 

f 

Look for ypserv and ypbind processes. If a ypserv process is running, 
type 

on the YP server. If ypwhich does not respond, ypserv has probably 
hung, and you should restart it. Type the following while logged in as 
superuser: 
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ypiet^ti /iiair/lib/ndtave/yp/ypiAcV 



If ps shows no ypserv process running, start one up. 

If the server's ypbind daemon is not running, start it up by typing the 
following: 



Notice that if you run ypbind and you type ypwhich immediately, 
ypwhich will return the error message not found in all cases. Run 
ypwhich again; it should now return the name of a server. 

If commands still hang, you may try the following: 
1 . Kill the existing ypbind: 



(■ 


ps -ef 1 


grepypbinc 










2. Restart ypbind with the ypset option that permits root to 
change the server: 


G 















3. Reset the server to one you know is reliable: 
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# ypset $ervmmme 



YP Service Is Unavailable 

When most machines on the network appear to be behaving normally, but one 
client cannot receive YP service, that client may experience many different 
sjnnptoms. For example, some conranands appear to operate correctly while 
others terminate with an error message about the unavailability of YP. Other 
commands limp along in a backup-strategy mode particular to the program 
involved. Still other commands or daemons crash with obscure messages or no 
message at all. Here are messages a client in this situation may receive: 



f 






$ ypcat inyf ile 






ypcat: can't bind to 


YP server for (Soinaln <domamnime> ^ 




Reason.: can 


ccnmonlcate with ypbind. 




V 





$ /usr/llb/netsvc/yp/yp/yppoll myfile 

yppolX: Sorry, I can't communicate with ypd:>ind. I give up. 



These symptoms usually indicate that the client's ypbind process is not run- 
ning. Run ps -ef and check for ypbind. If it you do not find it, log in as 
superuser and start by typing the following: 
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« /ttjsir/iib/netsvc/yp/ypbind 



YP problems should disappear. 

ypbind Crashes 

If ypbind crashes almost immediately each time it is started, look for a problem 
in some other part of the system. Check for the presence of the rpcbind dae- 
mon by typing the following: 



% p3 ax. I ^zep zpcbinci 



If it is not running, reboot. 

If rpcbind itself will not stay up or behaves strangely, look for more funda- 
mental problems. Check the network software in the ways suggested in the 
TCP/IP section in the Network User's and Administrator's Guide. 

You may be able to communicate with rpcbind on the problematic client from 
a machine operating normally. From the functioning machine, type: 



^ xpcinf a client \ gr^ yj^ind 



If rpcbind on the problematic machine is running normally, rpcinf o should 
produce an output similar to the following: 
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X00007 


3 


10Q0Q7 




3.00007 


3 


100007 


3 


1QQQQ7 


a 


X00007 


3 


100007 


3 











00 00 


10 \ 





tep Q.Q.0.0.12.1$IS^ duperusdr 

Ud)p^ 0.0.0.0.4.^ ^^Ind aupeafus^r 
ticit3 ^ 00 00 00 ypbind ^uperuaer 
tleotfl 07 00 00 00 ^Ind dupdxusdr 
1:ico1:90rd 0"^ tiO <)0 00 ypblnd 3^:^ruser 
Starlanclg 00 15»f sc. 30719700 201 00 00 00 00 00 00 00 10 

00 j 10 32v376 02 ypbind sn^rtiser 
fltarlan 00 15sfs<j.; 371 9700 201 00 00 00 C 

00 j 10 32v37€ 01 yj^lnd sup^rus^r 



There should be one entry per transport; in the preceding example, the entry for 
udp is missing. Because ypbind was not registered for it in this case, ypbind 
cannot run on udp. As long as there are other transports to run on, ypbind 
should run but the omission may indicate some kind of a problem. Reboot the 
machine and run rpcinf o again. If the ypbind processes are there and they 
change each time you try to restart /usr/lib/netsvc/yp/ypbind, reboot the 
system, even if the rpcbind daemon is running. 



ypwhich Displays Are Inconsistent 

When you use ypwhich several times on the same client, the resulting display 
may vary because the YP server changes. This is normal. The binding of YP 
client to YP server changes over time when the network or the YP servers are 
busy. Whenever possible, the network stabilizes at a point where all clients get 
acceptable response time from the YP servers. As long as your client machine 
gets YP service, it does not matter where the service comes from. For example, 
one YP server machine can get its own YP services from another YP server on 
the network. 



Debugging a YP Server 

Before trjdng to debug your YP server, read about the YP environment at the 
beginning of this chapter. Then look in this subsection for the heading that 
most closely describes the server's problem. 



11-42 



Programmer's Guide: Networking Interfaces 



Fixing YP Problems 



Servers Have Different Versions of a YP Map 

Because YP propagates maps among servers, occasionally you find different ver- 
sions of the same map at YP servers on the network. This version discrepancy 
is normal if transient, but abnormal otherwise. 

Most commonly, normal map propagation is prevented if it occurs when a YP 
server or router between YP servers is down. When all YP servers and the 
routers between them are running, ypxf r should succeed. 

If a particular slave server has problems updating maps, log in to that server 
and run ypxf r interactively. If ypxf r fails, it will tell you why it failed, and 
you can fix the problem. If ypxf r succeeds, but you suspect it has occasionally 
failed, create a log file to enable logging of messages. As superuser type the fol- 
lowing: 



( 

ypslavel cd fvajc/Y? 




ypslavel toach ypxfr.log 




V 


J 



This saves all output from ypxf r. The output resembles the output ypxf r 
displays when run interactively, but each line in the log file is time-stamped. 
You may see unusual orderings in the timestamps. This is normal - the time- 
stamp tells you when ypxf r started to run. If copies of ypxf r ran simultane- 
ously but their work took different amounts of time, they may actually write 
their summary status line to the log files in an order different from that in 
which they were invoked. Any pattern of intermittent failure shows up in the 
log. When you have fixed the problem, turn off logging by removing the log 
file. If you forget to remove it, it will grow without limit. 

While still logged in to the problem YP slave server, inspect the root's crontab 
file and the ypxf r* shell scripts it invokes. Typos in these files cause propaga- 
tion problems, as do failures to refer to a shell script within 
/var/spool/cron/crontabs/root, or failures to refer to a map within any 
shell script. 

Also, make sure that the YP slave server is in the map ypservers within the 
domain. If it is not, it still operates perfectly as a server, but yppush will not 
tell it when a new copy of a map exists. 
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If the YP slave server's problem is not obvious, you can work around it while 
you debug it using rep or tftp to copy a recent version of the inconsistent 
map from any healthy YP server. You must not do this remote copy as root, 
but you can probably do it while logged in as daemon. For instance, here is 
how you might transfer the map busted: 



ypaXav^l ciWKxJ go+w /var/yp/mydoinain 

$ rqp ypn«5ter:/var/yp/nvy<|0Rein/bi23t6dA* /var/yp/jnydomaln 
$ exit 

ypslav©# chown root /var/yp/jnydomaiix/Jxisted, * 
ypslavel chraod go-w /var/yp/raydoitialn 



Here the * character has been escaped in the command line so that it will be 
expanded on ypmaster, instead of locally on ypslave. Notice that the map 
files should be owned by root, so you must their change ownership after the 
transfer. 

ypserv Crashes 

When the ypserv process crashes almost immediately and does not stay up 
even with repeated activations, the debug process is virtually identical to that 
previously described in the subsection "ypbind Crashes." Check for the 
existence of the rpcbind daemon as follows: 



Reboot the server if you do not find the daemon. If it is there, type 
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and look for output similar to the following: 



IOOOO4 2 top O^O^OiO^l^.l^S ;^8erv 8\^>eru8er 

a00004 Z MOp 0.0.0,0.4,8 ypaerv supexuaer 

100004 2 tlcltd B 00 00 00 ypser^ auperuaer 

100004 2 ticot^ 06 00 00 00 ypserv aupexuser 

100004 2 ticot50£d 06 00 00 00 yp5^x^ supexuser 

100004 2 itarlaridg 00 15sfscS.2>21d?00 201 00 00 00 00 00 00 00 10 \ 

00 j 10 32v376 02 ypserv auperuser 
100004 2 dtarlm 00 153£3C.31319t00 201 00 00 00 00 00 00 00 10 \ 

OOj 10 32v376 01 ypserv superuser 



Your machine will have different port numbers. As in the case of ypbind, 
there should be one entry per transport. If a transport is missing, ypserv has 
been unable to register its services with it. Reboot the machine. If the ypserv 
processes are there, and they change each time you try to restart 
/usr/lib/netsvc/yp/ypserv, reboot the machine. 
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If ypserv on the master is disabled, you can no longer update any of the YP 
maps. On the other hand, if there is no ypserv daemon running but clients 
have ypbind running, machines may hang indefinitely until they find a 
ypserv. 

To turn off YP services safely, make sure all the clients stop running ypbind 
before ypserv in the master and slave servers is turned off. 
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Network Selection 



In order for network applications to be portable to different environments, the 
application process must have a standard interface into the number and types of 
networks available in any current environment. Network Selection provides a 
simple and consistent interface that allows user applications to select networks 
(at the transport level) that exist in an environment, thus enabling applications 
to be protocol- and media-independent. System V Networking Services applica- 
tions that allow the user to influence the choice of networks will use the stan- 
dard interface outlined here. 

Network Selection routines may be employed by the client portion of an appli- 
cation when the application initiates communication with its peer application on 
another machine; they may also be used by the server portion of an application 
when it offers its service. On a machine connected to a single network. Net- 
work Selection makes it possible for the application to make use of that network 
without requiring application-specific action by the administrator or user. On a 
machine connected to multiple networks. Network Selection makes it easy for 
the application to try each alternative network in turn, until it succeeds in estab- 
lishing communication, and to try them either in the order specified as the local 
"default" sequence established by the system administrator or in the order pre- 
ferred by the user. It also allows server-side applications to accept requests over 
multiple networks. 

Choosing among the available networks is the responsibility of the application. 
The Network Selection mechanism is intended to make that selection uniform 
and simple. 

How Network Selection Works 

The Network Selection component is built around 

■ a network configuration database (the /etc/netconf ig file) that contains 
an entry for each network on the system, and 

■ an optional NETPATH environment variable, set by a user and containing 
an ordered list of network identifiers. These network identifiers match the 
netconf ig network ID field and are used as links to the records in the 
netconf ig file. The netconf ig file is described in the next section. 

The Network Selection application programming interface consists of a set of 
network configuration database access routines. One set of library routines 
accesses only the netconf ig entries identified by the NETPATH environment 
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variable. These routines are described below under "Routines That Access 
netconf ig via NETPATH/' and on the getnetpath(3N) manual page. 

setnetpath ( ) 
getnetpath ( ) 
endnetpath ( ) 

Applications should use these routines that access NETPATH. They allow users 
to influence the selection of transports used by the application. If an application 
does not want the user to influence its decision, then the routines that access the 
netconf ig database directly should be used. 

There is also another group of routines that accesses netconf ig directly. These 
routines are described below under "Routines That Access netconf ig Directly/' 
and on the getnetconf ig(3N) manual page. 

setnetconf ig ( ) 
getnetconf ig ( ) 
endnetconf ig ( ) 

getnetconf igent ( ) 
f reenetconf igent ( ) 

In addition to this chapter, the System V Network Selection component is 
described in the System Administrator's Guide. 

The netconfig File 



The netconfig file is the database that describes all networks on a given 
machine. Entries in the netconfig file contain the following fields: 



network 


semantics 




protocol 


protocol 


network 


directory 


ID 






family 


name 


device 


lookup 














libraries 



network ID A locally meaningful representation of a network 

name (for example, tcp or starlan). Applications 
that require the name of a transport provider will 
obtain the name from this field. 
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semantics 



The semantics of the particular network. Valid seman- 
tics are: 



protocol family 



protocol name 



network device 



directory lookup libraries 



tpi_clts 
t placets 
tpi_cotsjord 



connectionless 

connection-oriented 

connection-oriented with orderly 
release 



Applications that require certain semantics, such as 
virtual circuit establishment, can use this field to deter- 
mine if the transport provider has the required seman- 
tics. 

A string of flags associated with the transf)ort. The 
only flag currently defined is a ''visible" flag, which is 
described under 'The NETPATH Environment Vari- 
able." flag may take one of two values, v or a hyphen 
H. 

The protocol family name of the transport provider, 
for example, inet or osinet. See the netconf ig(4) 
manual page. 

The protocol name of the transport provider. If proto- 
col family is inet, then protocol name is tcp, udp, or 
icitp. Otherwise the value of protocol name is a hyphen 
(-). See the netconf ig(4) manual page. 

The full pathname of the device file to open when 
accessing the transport provider. 

Names of the shared libraries. This field contains the 
comma-separated full pathnames of the directory 
lookup libraries that contain Name-to- Address Map- 
ping routines. The libraries niust be shared objects. 



The fields correspond to elements of the struct netconf ig structure. Pointers 
returned by Network Selection library routines are pointers to netconf ig 
entries in struct netconf ig format. The netconf ig structure is shown in 
Figure 12-1. 
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Figure 12-1: Tlie netconfig Structure 



3truct 



netconfig { 

: mi^lgned: i long ; 
tmdlgned long 

:: :Und i^GCL : lOAgv 

unsigned long 

unsigned long 
char 

unsigned long 



♦ncjjetldA /* network Identifier */ 

nc_s^nantics ; /* semantics of protocol */ 

ncjf Xag? /♦ flags for the j^rotocol */ 

tj<rjSir<3itofinly; /* family name */ 

ncjjroto; /* proto specific if fmly inet */ 

*ncjaevice; /♦ device nmm for mtworlc id */ 

nc_nlooJcups; /* # of entries in nc_lookup8 */ 

**nc^loolcups; /* list of loolcup directories */ 
ncjunusedta]; 



Valid network IDs are defined by the system administrator, who is responsible 
for ensuring that network IDs are locally unique. If they are not, some Network 
Selection routines cannot operate in a well-defined manner. For example, it is 
not possible to know which network getnetconf igent ("starlan") will use 
if there are two netconfig entries with the network ID starlan. 

The system administrator also determines the order of the entries in the 
netconfig database. The routines that retrieve entries from 
/etc/netcdnf ig return entries in order, beginning at the top of the file. The 
order of networks in the netconfig file therefore becomes the default network 
search path for applications using the routines described in the next section. 

The netconfig file and the struct netconfig structure are described in 
greater detail on the netconf ig(4) manual page. 



The NETPATH Environment Variable 

In most cases the user isn't interested in which network is used for a network 
operation. Typically an application uses the default network search path esta- 
blished by the systenri administrator to locate an available network. However, 
when a user wants to influence the choices made by an application, the applica- 
tion can modify the interface by using the shell variable NETPATH and the rou- 
tines described in the next section. These routines access only the networks 
specified in the NETPATH variable. 
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NETPATH is similar to the PATH variable. It consists of a colon-separated list of 
network IDs. Each network ID in the NETPATH variable corresponds to the net- 
work ID field of a record in the netconf ig file. A literal colon can be embed- 
ded as "\:'' and a literal backslash as "\V'. NETPATH is described on the 
environ(5) manual page in the User's Reference Manual 



Figure 12-2: Sample values for a NETPATH environment variable. 

ilBllII 

NETPATH-starlan : tcp 



J 



The set of default networks is different for the routines that access netconf ig 
via the NETPATH environment variable (described in the next section) and the 
routines that access netconf ig directly (described later in this chapter). The 
set of default networks for routines that access netconf ig via NETPATH con- 
sists of the "visible" networks in the netconf ig file. For routines that access 
netconf ig directly, the set of default networks is the entire netconf ig file. 
A network is "visible" if the system adnunistrator has included a v flag in the 
flag field of that network's netconf ig entry. 



Routines That Access netconfig via NETPATH 

The three routines described in this section access the network configuration 
database indirectly through the NETPATH environment variable. The user is 
thus able to specify the network or networks the application is to use and, if 
more than one network is specified, in what order they are to be tried. These 
routines have the following syntax: 
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iiiiiiiilpliiliiiiiiii 

atrwot netconf ig * 
gdtnet|>ath (hatidlep) 
VQld * handlep; 

endnetpat^ (hanfllep) 
void * haridlep; 

V J 

A call to setnetpath ( ) has the effect of initializing NETPATH. It returns a 
pointer to a database that contains the entries sf>ecified in a NETPATH variable. 
The pointer, called a "handle/' is used when traversing this database with get- 
netpath 0 . Each call to setnetpath () returns a different database pointer, 
setnetpath 0 must be called before the first call to getnetpath ( ) and may 
be called at any other time, setnetpath ( ) returns NULL if the netconf ig 
database is not present, setnetpath ( ) takes no arguments. 

When first called, getnetpath ( ) returns a pointer to to the netconf ig data- 
base entry that corresponds to the first component of the NETPATfi variable (the 
instance described by the handle). NETPATH components are read from left to 
right. The netconf ig entry is formatted as a struct netconf ig. On each 
subsequent call, getnetpath ( ) returns a pointer to the netconf ig entry that 
corresponds to the next component of the NETPATH variable, getnetpath () 
returns NULL on end of file. A call tq getnetpath () without an initial call to 
setnetpath 0 will produce an error, getnetpath () takes a handle as an 
argument 

getnetpath ( ) silently ignores invalid NETPATH components. A NETPATH 
component is invalid if there is no corresponding entry in the netconf ig data- 
base. 

If the NETPATH variable is unset, getnetpath () behaves as if NETPATH were 
set to thet sequence of "default" or "visible" networks in the netconf ig data^ 
base, in the order in which they are listed. 
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endnetpath 0 is called to "free" the database pointer to elements in the NET- 
PATH variable when processing is complete. It returns 0 on success and -1 on 
failure, endnetpath () will fail if setnetpath () was not called previously, 
endnetpath 0 takes the instance handlep as an argument. 



Figure 12-3: Sample code using setnetpath( ), getnetpath( ), and endnetpath () . 



r 



void *handXop; 



U ((handlep * aetnetpathO> — IHJEL) { 
jicj>6rror (StgV J D J ) ; 
^it(l); 



(j(n0tcciifl9P *^ getnetpatliL (handlep)) !- now.) { 

* netconf Igp now describes a transport provider 



*/ 



endnetpath (handlep) ; 



Routines That Access netconfig Directly 



Five functions access the network configuration database file, 
/etc/netconf ig. They have the following syntax: 
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void * 

^txofX netconf ig * 
gettiettitinf ig (handlep) 
void * handlep; 

llliiisiiiiiiiiiiiiiiii 

encjnetcoptlg (Iwadlcq?) 
void * haixJXep; 

V , J 

A call to setnetconf ig 0 initializes the database routines. It returns a data- 
base pointer to be used when traversing the database with getnetconf ig () . 
This database pointer is also called a handle. Each call to setnetconf ig () 
returns a different database pointer. Each call to getnetconf ig () returns the 
next entry in netconf ig associated with the "handle'' returned by set- 
net configO . 

When first called, getnetconf ig {) returns a pointer to the first entry in the 
netconf ig database, formatted as a struct netconf ig. On each subsequent 
call, getnetconf ig 0 returns a pointer to the next entry in the database; it can 
thus be used to search the entire netconf ig file, getnetconf ig () returns 
NULL to the calling routine at end of file. 

endnetconf ig 0 may be called to "free'' the database pointer when process- 
ing is complete, endnetconf ig () may not be called before setnetcon- 
f ig 0 . endnetconf ig 0 returns 0 on success and -1 on failure (for example, 
if setnetconf ig 0 was not called previously). 
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Figure 12-4: Sampie code using setnetconfigC ), getnetconfigC ), and 
endnetconfig ( ) . 



V6id * hindX^I); 

* tran5^6rt pro^ldei^ Infoxmatlon is descxlbod in netcfp. 

* prQo^ssjtranaport is a via^r^sufiplieKii routine that trli^s to 

* OQ(m«K:it to a servtetr cmt transport iMftcTp. 



lAiil^ <<netcfp ^ g«tnetcc«fig<han<lXep>> I- NOtt) { 

if (processjiranaport {netcf p) *«• SDDCESS) { 
breajc; 



) 



) 



endnetconfig (handlep) ; 



Figure 12-5: Sampie Code Using getnetconf igent ( ) and freenetconfigent () 



♦include <r»tCQn£ig ,h> 

Struct netcottf ig * 
getnetconf igent (netid) 
char ♦ netid; 

int 

freenetconfigent (netconf igp) 
struct netconf ig ^ netoonf igp; 
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getnetconfigent () returns a pointer to the struct netconf ig structure 
corresponding to netid. It returns NULL if netid is invalid (that is, does not 
name an entry in the netconf ig database). 

freenetconfigent () frees the structure returned by getnetconfigent () 
setnetconf ig 0 need not be called before getnetconfigent () . 

wm 



Figure 12-6: Sample code using getnetconfigent () and freenetconfigent (). 



* assume starlaxi Is a netid on this machine 



struct netconf ig * netcfp; 

if ((netcfp - getnetconfigent Cstarlan")) — NOLL) J 
ncjerror(*no informati<ax abcwt stari^**); 
exitd); 

illiiiliiiiiliiiliiil 



prooess^transport (netcfp) ;; 
freenetconfigent (netcfp) ; 



Code Examples 

The following code examples are taken from the larger program at the end of 
this section. They show several of the ways in which the Network Selection 
facility may be used. , 
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Looping through All "Visible" netconfig Entries 

In the examples, the setnetpath () call initializes the Network Selection rou- 
tines and returns a database pointer. 

The getnetpath 0 call returns each visible entry in the /etc/netconf ig file 
(that is, each entry that contains a v flag). Entries are returned in the order in 
which they appear in the file. 

fprlntf <stdarr, ERROR: network selectibn not det\n", argv(0]); 

exitd); 

liiiiiilliilliliiilli 

vrtiile ((netconficjp - getnetpath <)> I*. KULL) { 

::||:;|;||||||||||||||| 

* the netCOTiflg structure contains information about the 

* transport provider. 

\ J 



Looping through User-defined netconfig Entries 

Users can also manipulate the loop by setting the NETPATH environment vari- 
able to a colon-separated list of transport provider names (transport provider 
names are given in the first field of the /etc/netconf ig file). If the value of 
NETPATH is set as follows: 



iiEa4>«tH«t<5p : starXan 



J 



then the loop will first return the entry corresponding to top, and then the 
entry corresponding to starlan. If NETPATH is not set in the environment, the 
above loop will return all visible entries in the netconfig file in the order in 
which they appear there. 
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The NETPATH environment variable allows users to define the order in which 
client-side applications attempt to make connections to a service. It also allows 
the administrator of the server machine to restrict which transport providers a 
service will loop through and bind to. 

Looping through All netconfig Entries 

An apphcation can ignore the NETPATH variable and loop through all entries in 
the netconfig file - even those without a v flag: 



fpirintf (atdarr, ns: ERRO£l: network aeleetioti tkt3it a^\n**, az^v^OJ); 

while ( (netconf igp - getnetconf ig 0 > !- NULL) { 

* the netconfig structure contains information about the 

♦ transport pijovi^er, an<J NETPATH is ignored. 



Specifying a Single Transport Provider 

The following call will obtain information about a single, named transport pro- 
vider: 



netconf Igp - getnetconf igt^t (naind> ; 
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The Name-to-Address Mapping feature allows an application to obtain the 
address of a service on a specified machine in a transport- independent manner. 
The Name-to-Address Mapping feature consists of the following routines: 

ne t di r_ge t byname 
ne t di r_ge t byaddr 
netdir_f ree 
netdir_mergeaddr 
taddr2uaddr 
uaddr2taddr 
ne t di r_opt ions 

Each routine takes a pointer to a struct netconf ig, which describes a tran- 
sport provider. Using the directory lookup library element of the netconf ig 
structure, the routine can obtain a list of shared libraries that contains 
transport-specific versions of itself. It will call each of these in turn until the call 
succeeds. For example, in UNIX System V Release 4.0, the full libraries are pro- 
vided to support the Internet protocols, the ISO STARLAN protocols, and the 
loopback protocols. 

The libraries are: 

tcpip . so Contains the Name-to-Address Mapping routines for the Inter- 
net protocol suite. 

straddr . so Contains the Name-to-Address Mapping routines for any proto- 
col that accepts strings as addresses. ISO and the loopback pro- 
tocols are examples. 

The routines are described below under 'The Name-to-Address Mapping Rou- 
tines," and on the netdirON) manual page. The struct netconfig struc- 
ture is described on the netconf ig(4) manual page. 
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The Name-to-Address Mapping Libraries 

Files for each of the libraries must be created and maintained by the system 
administrator. 

tcpip. so 

The routines in this dynamic library create addresses from the /etc/hosts and 
/etc/services files available with the TCP/IP package. The /etc/hosts 
file contains two fields, the machine's IP address and the machine name. For 
example: 



r 










X9a.H.X08.01 


bilbo 








192.11,108.1$ 


elvl? 






V 






J 



The /etc/services file contains two fields, a service name and a port number 
with one of two protocol specifications, either tcp or udp. For example: 



tpcblftd m/udp 

rpcbincl lU/tcp 

logltt 513/t<^ 

listen 1025/tqp 



When an application uses this library to request the address of a service on a 
particular host, the host name must appear in the /etc/hosts file and the ser- 
vice name must appear in the /etc/services file. If one or the other does 
not appear, an error will be returned by the Name-to-Address Mapping rou- 
tines. 

straddr . so 

The routines in this dynamic library create addresses from files that have the 
same format as the tcpip . so files described above. The straddr . so files are 
/etc/net/transporf/hosts and /etc/net/transporf/services. transport is 
the local name oiF the transport provider that accepts string addresses (specified 
in the network ID field of the /etc/netconf ig file). For example, the host file 
for starlan would be /etc/net /starlan/hosts, and the service file for 
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starlan would be /etc/net/starlan/services. For starlandg, the files 
would be /etc/net/starlandg/hosts and 
/etc/net /starlandg/services. 

Even though most string addresses do not distinguish between "host" and "ser- 
vice/' separating the string into a host part and a service part provides con- 
sistency with other transport providers. The /etc/net/transport/hosts file 
will therefore contain a string that is considered to be the machine address, fol- 
lowed by the machine name. For example: 



/ 


r 






bilbdacSdr 














frodo 






J 


The /etc/net /transport/ services file contains service names followed by 


strings identif}dng the service ports. For example: 


/ 








ipcbind ipc 






listen secv^t 




V 


J 



The routines create the full string address by combining the "host address" and 
the "service port," separating the two with a dot ("."). For example, the 
address of the "listen" service on bilbo would be bilboaddr . serve, and the 
address of the "rpcbind" service on bilbo would be bilboaddr . rpc. 

When an application requests the address of a service on a particular host on a 
transport provider that uses this library, the host name must appear in 
/etc/ net /transport/hosts and the service name must appear in 
/etc/net /transport/ services. If one or the other does not appear, the 
Name-to-Address Mapping routines will return an error. 
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Using the Name-to-Address Mapping Routines 



netdir _c^eftbynaine<netcon£ig, ndjiostserv, ndjaddrllsty 
stJCUCt i»et<»nf Ig *iietconf ig; 

attuGt ndhostserv *ndJiostserv; 
struct ndjiddrllst **rijKidrlist? 

net<Ur_get)>ya<JcJr(notconjig^ nd^hostseirvUat, netl>uf> 
dtnict mtcotitig *netco«ifig; 
struct ndjiostservllst. **ndJiostservllst; 
struct neti>uf . *netbut; 



void 

netdirjf ree (ptr^ 
char *ptr; 
int t^; 



type) 



char ♦ 

taadr2uadkjr(n^tconfig» addr) 

struct netcOnf Ig *netcoiif Ig; 

struct netbuf *addr; 

struct netbuf * 

uaddr2ta<Jdr(netc<^fig# acJdr) 

struct ttetcotif ig *netconf ig? 

cHar *addr; 

lllliiiillllllllll^ 

netdir^optlons (netconfig, option, fd, pointer_to__args^ 

strvKSt netconf ig *netconf ig; 

itit opticn; 

int fd; 

Char *poittter_to_args; 

void 

netdlrjpetzor ( s ) 
char ♦s; 

char * 

netdlrjsperror ( ) 
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netdir_getbyname 

The netdir_getbyname () routine maps the machine and service name 
specified in the nd_hostserv structure to a collection of addresses of the type 
understood by the transport identified in the netconf ig structure. The 
nd_addrlist parameter returns a pointer to the addresses. To find all 
addresses of a machine and service (on all available transports), repeatedly call 
the netdir_getbyname () routine with each netconfig structure returned 
by the getnetpath(3N) call. 

netdir_getbyaddr 

The netdir_getbyaddr 0 routine maps addresses into machine and service 
names. Given an address in the netbuf parameter, this routine returns a list of 
machine name and service name pairs that would )aeld that address (a pointer 
to the list of machine and service name pairs is returned in the 
nd_hostservlist parameter.) 

netdir_free 

The netdir_f ree () routine frees the structures allocated by the name-to- 
address translation routines. The parameters can take the following values: 



Type 


Pointer 


ND_HOSTSERVLIST 


pointer to 

nd_hostservlist struc- 
ture allocated by 
netdir_getbyaddr 0 


ND_ADDRLIST 


pointer to nd_addrlist 
structure allocated by 
netdir_getbyname () 



taddr2uaddr 

The taddr2uaddr () routine translates the address given in the netbuf struc- 
ture (which is an address for the transport provider given in the netconfig 
structure) and returns a "universal address" representation of the address. A 
"universal address" is a machine architecture-independent character representa- 
tion of the address. 
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uaddr2taddr 

The uaddr2taddr routine takes a "universal address" and translates it back 
into a netbuf structure. The netconf ig parameter specifies which transport 
provider the address is valid for. 

netdir_options 

The netdir_options () routine provides an interface to transport specific 
capabilities (for example, applications can take advantage of the "broadcast 
address" and "reserved port" facilities provided by the User Datagram Protocol 
( UDP)). 

The netconf ig structure specifies a transport provider. The option argument 
specifies the transport-specific action to take. The third argument is a file 
descriptor (which may or may not be used depending upon option). The fourth 
argument is a a pointer to operation-specific data. 

The following values may be used for option: 

ND_SET_BROADCAST This option sets the transport provider up to 

allow for broadcast (if the transport provider 
supports broadcast), fd is a file descriptor into 
the transport provider (for example, the result of 
at_open() of /dev/udp). pointer Jojirgs is 
not used. If successful, broadcast operations 
may be done on fd, 

ND_SET_RESERVEDPORT Allows the application to bind to a reserved 

port, if allowed by the transport provider 
specified, fd is a file descriptor into the tran- 
sport (it must not be bound to an address). If 
pointer Jo jirgs is NULL, fd will be bound to a 
reserved port. If pointer Jo jirgs is a pointer to a 
netbuf structure, an attempt will be made to 
bind to a reserved port on tt\e specified address. 

ND_CHECK_RESERVEDPORT If the concept of a reserved port exists for a 

transport provider, ND_CHECK_RESERVEDPORT 
is used to verify that an address corresponds to 
a reserved port, fd is not used, pointer Jo _args 
is a pointer to a netbuf structure that contains 
an address. This option returns 0 only if the 
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address specified in pointer Jo jirgs is reserved. 

ND_MERGEADDR Used to transform a locally meaningful address 

into an address that client machines can connect 
to. For example, the Transmission Control Pro- 
tocol (TCP) has the concept of 0 . 0 . 0 . 0 as a 
locally meaningful address. NDJMERGEADDR can 
be used to translate the 0 . 0 . 0 . 0 address into a 
"real" address that is understood by client 
machines, fd is not used with this option. 
pointer Jo jirgs is a pointer to a nd_mergearg 
structure, which has the following form: 



f 










} 

V 


<!har *sMiaddr; 
char *cjiia<3c|r; 
Char *>njaaddr; 


/* 
/♦ 


server's universal address **/ 
client's universal address */ 
the result */ 













netdir_j>error 

The netdir_perror () routine prints onto standard output the error message 
stating why one of the name-to-address mapping routines failed. The error 
message is preceded by the string given as an argument. 

netdir_sperror 

The netdir^sperror 0 routine returns a string containing the error message 
stating why one of the name-to-address mapping routines failed. 



Network Selection and Name-to-Address Mapping 



12-19 



Name-to-Address Mapping 



Figure 12-7: Code exampie: Using Networic Selection and Name-to-Address 
Mapping. 



iincluda <n6!tcQnfl9.h> 
flAoludd <tk6tdit.h> 
41hcX»de <tivs«r.h> 



/*^* Ttke following i9 a 99gm^t of a procedure. ***/ 



tftxruct ttdhotttst^erv tid^boertaerv/ 

struct netconfig *netCOiif ijgp; 

struct nd_addrll8t *nd_addrlistp; 

iStrudt ttebbuf *t>etbufp; 
iv^ 1; 
void *handLep; 



/* cotxbaiius lio«t and servixie infounatl^ */ 
/* contalna infopmtion about each qa«twprlc */ 
/* list of addresses fox the servioe: */ 
/* the address ctf thfe service */ 
/* counts the nwiiber of addbcesses */ 
/* a handle ixxto netwrJc selection */ 



* Set the host strtioture to reference the "date" setv^ioe on nadhine "gandalf* 



ndjiosts^rv.h^host «« ^gandalf"; 
»d_ho9tserv,h^8exv » ^date"; 

* Znitialiice the netirork selection mechanism. 



if (<handlep » setnetpathO) MOLL) { 
nc,j>er£oif (argv [0] ) / 
exit (1> 

* hoop through the transport providers. 

while ((aetconfigp « gefenstpath (faandlep) ) 1** MOLL) { 

* Print out the inforwation associated with the transport 

* provider described in the ''netconfig" structure. 

pritttf ("Stran^tt provider name: %s\n", netconfigp->nc^netld) ; 
^intf ("transfport protocol family: %s\n*'/ netoc«ifigp->ncjprotofmly) ; 
prlntfCThe trana^port device file; %s\n'', netconf igp->ncjievioe) / 
printf ("transport provider semantics : ; 



(continued on next page ) 
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Figure 12-7: Code example: Using Network Selection and Name-to-Address 
Mapping, (continued) 



Bwltdn <n«teonfigi>^>«iejHmaintlc8) { 

prints virtual clrciiit\n''ll ; 
breaJc; 

pzriAtf ("virtti*! circuit Mlth ordwcXy x»i«M«iSiv'^); 
prtntf ("d»tttgruii\a*) ; 

* Get the ac)dre09«ff for servioe *dftte* <^ machine *gax»dalf * 

* over title transport provider specified in the netconf ig structure, 

llllillllllllll;;;;;:^^ 

if <iiet<tir_cretbyname(netconfigpy &nd_hofft9etv^ AndLadctriistp) J» 0) { 
printf ("Cannot determine the address for the setviceV^")/ 
netdir jp<rror (ar^vfOl )' ; 
contitme; 

printf (**!niere are <*cb' addresses for the date service on gandalf ;\n^, 
nd_addrlistp^>njc&t) ; 



Srlnt out all addr^^ses for service "date" act machine "gtAdalf"^ 
4m the current transport proyidn:. 



hetbufp - nd_addrlistp->n_addrs; 

for (i » 0; i < nd_addrXistp->njcnt; i++) l 

printf ('*%s\tt", taddr2uadde (netconf i^, netliMQ))) ; 

netbufp++; 



endnctconf ig (handles^): ; 
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Introduction 



The Service Access Facility (SAF) generalizes the procedures for service access so 
that login access on the local system and network access to local services are 
managed in similar ways. Under the SAF, systems may access services using a 
variety of port monitors, including ttyition, the listener, and port monitors writ- 
ten expressly for a user's application. The Service Access Facility is fully docu- 
mented in the "Service Access" chapter of the System Administrator's Guide, It is 
assumed that programmers who are writing port monitors to be used on a Sys- 
tem V Release 4 system are familiar with that chapter. 

Beginning with System V Release 4, ttymon replaces getty and uugetty for 
local access to login service and is available for other types of access to tiie local 
system. The "Service Access" chapter of the System Administrator's Guide 
describes managing ttymon port monitors ('The Port Monitor ttymon") and 
defining terminal line settings for TTY ports ('Terminal Line Settings"). 

The listener provides network access over any network that conforms to the 
Transport Interface (TLI) protocol. The listener is also documented in the Ser- 
vice Access chapter of the System Administrator's Guide. TLI is documented in 
Chapter 2 of this volume, 'Transport Interface Programming." 

Service Access Facility manual pages are included in the System Administrator's 
Reference Manual and in Appendix A of this volume. 

Programmers of networking applications should also see Chapter 12 of this 
volume, "Network Selection and Name-to-Address Mapping." 

This chapter gives a brief description of the functions a port monitor must per- 
form to run under the Service Access Facility; the message format required for 
port monitor interface with the SAF; the way in which the SAF administers port 
monitors; and the requirements for port monitors registered with the SAF. The 
chapter also contains a section on configuration files, the language in which 
configuration scripts are written, and the doconfigO function, which interprets 
these scripts. Finally, it includes code for a simple port monitor that may be 
used as a model. 
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Overview of the Service Access Facility 



The manner in which a port monitor monitors and manages access ports is 
specific to the port monitor and not to any component of the Service Access 
Facility. Users may therefore extend their systems by developing and installing 
their own port monitors. It is one of the important features of the Service 
Access Facility that it can be extended in this way by users. 

From the point of view of the Service Access Facility, a service is a process that 
is started. There are no restrictions on the functions a service may provide. 

The Service Access Facility consists of a controlling process, the Service Access 
Controller (SAC), and two administrative levels corresponding to two levels in 
the supporting directory structure. The top adnunistrative level is concerned 
with port monitor administration, the lower level with service administration. 

From an administrative point of view, the Service Access Facility consists of the 
following components: 

■ The Service Access Controller 

■ A per-system configuration script 

■ The SAC administrative file 

■ The SAC administrative command sacadm 

■ Port monitors 

■ Optional per-port monitor configuration scripts 

■ An administrative file for each port monitor, named _pmtab 

■ The administrative command pmadm 

■ Optional per-service configuration scripts 



The Service Access Controller 

The Service Access Controller is the Service Access Facility's controlling process. 
The SAC is started by init(lM) by means of an entry in /etc/inittab. Its 
function is to maintain the port monitors on the system in the state specified by 
the system administrator. 
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The administrative command sacadm is used to tell the SAC to change the state 
of a port monitor, sacadm can also be used to add or remove a port monitor 
from SAC supervision and to list information about port monitors known to the 
SAC. 

The SAC's administrative file contains a unique tag for each port monitor known 
to the SAC and the pathname of the command used to start each port monitor. 

The SAC performs three main functions. Briefly: 

■ it customizes its own environment 

■ it starts the appropriate port monitors 

■ it polls its port monitors and initiates recovery procedures when necessary 
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Basic Port Monitor Functions 



A port monitor is a process that is responsible for monitoring a set of homo- 
geneous, incoming ports on a machine. A port monitor's major purpose is to 
detect incon[iing service requests and to dispatch them appropriately. 

A port is an externally-seen access point on a system. A port may be an 
address on a network (TSAP or PSAP), a hardwired terminal line, an incoming 
phone line, etc. The definition of what constitutes a port is strictly a function of 
the port monitor itself. 

A port monitor performs certain basic functions. Some of these are required to 
conform to the Service Access Facility (SAP); others may be specified by the 
requirements and design of the port monitor itself. 

Port monitors have two main functions: 

■ managing ports and 

■ monitoring ports for indications of activity 



Port iVlanagement 

The first function of a port monitor is to manage a port. The actual details of 
how a port is managed are defined by the person who defines the port monitor. 
A port monitor is not restricted to handling a single port; it may handle multi- 
ple ports simultaneously. 



NOT£ 



Some examples of port management are setting the line speed on incoming 
phone connections, binding an appropriate network address, reinitializing the 
port when the service terminates, outputting a prompt, etc. 
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Activity Monitoring 

The second function of a port monitor is to monitor the port or ports for which 
it is responsible for indications of activity. Two types of activity may be 
detected. 

■ The first is an indication to the port monitor to take some port monitor- 
specific action. Pressing the <break> key to indicate that the line speed 
should be cycled is an example of a port monitor-specific activity. Not all 
port monitors need to recognize and respond to the same indications. The 
indication used to attract the attention of the port monitor is defined by 
the person who defines the port monitor. 

■ The second is an incoming service request. When a service request is 
received, a port monitor must be able to determine which service is being 
requested from the port on which the request is received. Note that the 
same service may be available on more than one port. 



Other Port l\/lonitor Functions 

Restricting Access to tlie System: Enabiing and Disabiing Port 
Monitors and Ports 

A port monitor must be able to restrict access to the system without disturbing 
services that are still running. In order to do this, a port monitor must maintain 
two internal states: enabled and disabled. The port monitor starts in the state 
indicated by the ISTATE environment variable provided by the sac. (See "The 
Service Access Controller/Port Monitor Interface/' below.) 

Enabling and Disabling a Port Monitor 

Enabling or disabling a port monitor affects all ports for which the port monitor 
is responsible. If a port monitor is responsible for a single port, only that port 
will be affected. If a port monitor is responsible for multiple ports, the entire 
collection of ports will be affected. 

Enabling or disabling a port monitor is a dynamic operation: it causes the port 
monitor to change its internal state. The effect does not persist across new invo- 
cations of the port monitor. 
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Enabling and Disabling a Port 

Enabling or disabling an individual port, however, is a static operation: it causes 
a change to an adniinistrative file. The effect of this change will persist across 
new invocations of the port monitor. 

Creating utinp Entries 

Port monitors are responsible for creating utirp entries with the tj^ field set to 
USERJPRCX::eSS for services they start, if this action has been specified (that is, if 
-f u was specified in the pmdm line that added the service). These utnp entries 
may in turn be modified by the service. When the service terminates, the utnp 
entry must be set to DEAD__PROCESS. 

Port i\/lonitor Process IDs and Locic Files 

When a port monitor starts, it writes its process id into a file named _jpid in the 
current directory and places an advisory lock on the file. 

Changing the Service Environment: Running doconflgO 

Before invoking the service designated in the port monitor administrative file, 
jpmtab, a port monitor must arrange for the per-service configuration script to 
be run (if one exists) by calling the library function doconfig(3N) . Because the 
per-service configuration script may specify the execution of restricted com- 
mands, as well as for other security reasons, port monitors are invoked with 
root permissions. The details of how services are invoked are specified by the 
person who defines the port monitor. 

Flies: The Port Monitor Administrative File 

A port monitor's current directory contains an administrative file named 
jpmbab. _pmtab is maintained by the pinadm command in conjunction with a 
port monitor-specific administrative command. Port monitor-specific commands 
are discussed below. 



HOTE 



The port monitor-specific administrative command for a listen port monitor 
is nlsadmin(IM); the port monitor-specific administrative command for 
ttyxnon is ttyadm. Any port monitor written by a user must be provided witli 
an administrative command specific to tliat port monitor to perform similar 
functions. 
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Files: Per-service Configuration Fiies 

A port monitor's current directory also contains the per-service configuration 
scripts, if they exist. The names of the per-service configuration scripts 
correspond to the service tags in the _pmtab file. 

Private Port Monitor Fiies 

A port monitor may create private files in the directory /var/saf /tag, where tag 
is the name of the port monitor. Examples of private files are log files or tem- 
porary files. 

Terminating a Port l\/lonitor 

A port monitor must tenninate itself gracefully on receipt of the signal SIGTERM. 
The termination sequence is the following: 

■ The port monitor enters the stopping state; no further service requests are 
accepted. 

■ Any attempt to re-enable the port monitor will be ignored. 

■ The port monitor yields control of all ports for which it is responsible. It 
must be possible for a new instantiation of the port monitor to start 
correctly while a previous instantiation is stopping. 

■ The advisory lock on the process id file is released. Once this lock is 
released, the contents of the process id file are undefined and a new invo- 
cation of the port morutor may be started. 
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The sac creates two environment variables for each port monitor it starts: 

■ PMTAGand 

■ ISTATE 

PMTAG is set to a unique port monitor tag by the sac. The port monitor uses 
this tag to identify itself in response to sac messages. ISTATE is used to indi- 
cate to the port monitor what its initial internal state should be. ISTATE is set to 
"enabled" or "disabled" to indicate that the port monitor is to start in the 
enabled or disabled state, respectively. The sac performs a periodic sanity poll of 
the port monitors. 

The sac communicates with port monitors through FIFOs. A port monitor 
should open _pnpipe, in the current directory, to receive messages from the sac 
and . . /_sacpipe to send return messages to the sac. 

l\/lessage Formats 

This section describes the messages that may be sent from the sac to a port 
monitor (sac messages), and from a port monitor to the sac (port monitor mes- 
sages). These messages are sent through FIFOs and are in the form of C struc- 
tures (see the section "The Header File sac.h"). 

sac Messages 

The format of messages from the sac is defined by the structure sacmsg: 

struct sacmsg { 

int sc_size; /* size of optional data portion */ 
char sc_type; /* type of message */ 

}; 

The sac may send four t)^s of messages to port monitors. The type of mes- 
sage is indicated by setting the scjtype field of the sacmsg structure to one of 
the following: 
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SC_STATUS Status request 

SCJSNABLE enable message 

SCJDISABLE disable message 

SC_READDB message indicating that the port monitor's 

_pmtab file should be read 

sc_size indicates the size of the optional data part of the message. It is dis- 
cussed under "Message Classes/' below. For System V Release 4, sc_size 
should always be set to 0. 

A port monitor must respond to every message sent by the sac. 

Port Monitor Messages 

The format of messages from a port monitor to the sac is defined by the struc- 
ture pmmsg: 

struct pnmsg { 

char pm_type; /* type of message */ 

unchar pm_state; /* current state of port monitor */ 
char pmjnaxclass; 1^ maximum message class this 

port monitor understands */ 
char pm_tag[PMTAGSIZE + 1]; 

/* port monitor's tag */ 
int pm_size; /* size of optional data portion */ 

}; 

Port monitors may send two types of messages to the sac. The type of message 
is indicated by setting the pm_type field of ttie pirmsg structure to one of the fol- 
lowing: 

PM_STATUS state information 

PM__UNKNOWN negative acknowledgement 

For both types of messages, the pm_tag field is set to the port monitor's tag and 
the pm_state field is set to the port monitor's current state. Valid states are: 

PM_STARTING Starting 

PM_ENABLED enabled 

PM_DISABLED disabled 

PM_STOPPING stopping 

The current state reflects any changes caused by the last message from the sac. 
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The status message is the normal return message. The negative acknowledg- 
ment should be sent only when the message received is not understood. 

pm_size indicates the size of the optional data part of the message, 
pmjnaxclass is used to specify a message class. Both are discussed under 
"Message Classes" below. For System V Release 4, {anjnaxclass should always 
be set to 1 and sc_size should always be set to 0. 

Port monitors may never initiate messages; they may only respond to messages 
that they receive. 



Message Classes 

The concept of "message class" has been included to accommodate possible SAF 
extensions. The messages described above are all "class 1" messages. None of 
these messages contains a variable data portion; all pertinent information is con- 
tained in the message header. 

If new messages are added to the protocol, they will be defined as new message 
classes (for example, class 2). The first message the sac sends to a port monitor 
will always be a class 1 message. Since all port mohitors, by definition, under- 
stand class 1 messages, the first message the sac sends is guaranteed to be 
understood. In its response to the sac, the port monitor sets the pmjmaxclass 
field to the maximum message class number for that port monitor. The sac will 
not send messages to a port monitor from a class with a larger number than the 
value of pmjtBxclass. Requests that require messages of a higher class than 
the port monitor can understand will fail. For System V Release 4, 
pmjnaxclass should always be set to 1. 



For any given port monitor, messages of class pnynaxclass and messages 
of all classes with values lower than pmjnaxclass are valid. Thus, if the 
pmjnaxclass field is set to 3, the port monitor understands messages of 

classes l, 2, and 3. 

Port monitors may not generate messages; they may only respond to messages. 
A p>ort monitor's response must be of tfie same class as the originating message. 

Since only the sac can generate messages, this protocol will function even if the 
port monitor is capable of dealing with messages of a higher class than the sac 
can generate. 
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pm_size (an element of the pnmsg structure) and sc_size (an element of the 
sacmsg structure) indicate the size of the optional data part of the message. The 
format of this part of the message is undefined. Its definition is inherent in the 
type of message. For System V Release 4, both sc_size and pm_size should 
always be set to 0. 
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The SAC Administrative File sactab 

The SACs administrative file contains information about all the port monitors 
for which the SAC is responsible. This file exists on the delivered system. Ini- 
tially, it is empty except for a single comment line which contains tt\e version 
number of the Service Access Controller. Port monitors are added to the system 
by making entries in the SAC's administrative file. These entries should be 
made using the administrative command sacadm with a -a option, sacadm is 
also used to remove entries from the SACs administrative file. 

Each entry in the SACs administrative file contains the following information: 

PMTAG A unique tag that identifies a particular port monitor. The sys- 

tem administrator is responsible for naming a port monitor. 
This tag is then used by the Service Access Controller (SAC) to 
identify the p)ort monitor for all administrative purposes. 

PMTAG may consist of up to 14 alphanumeric characters. 

PMTYPE The type of the port monitor. In addition to its unique tag, each 

port monitor has a type designator. The type designator 
identifies a group of port monitors that are different invocations 
of the same entity, ttymon and listen are examples of valid 
port monitor types. The type designator is used to facilitate the 
administration of groups of related port monitors. Without a 
type designator, the system administrator has no way of know- 
ing which port monitor tags correspond to port monitors of the 
same type. 

PMTYPE may consist of up to 14 alphanumeric characters. 

PLCS The flags that are currently defined are: 

d When started, do not enable the port monitor. 

X Do not start the port monitor. 

If no flag is specified, the default action is taken. By default a 
port monitor is started and enabled. 

RCNT The number of times a port monitor may fail before being 

placed in a failed state. Once a port monitor enters the failed 
state, the SAC will not try to restart it. If a count is not specified 
when the entry is created, this field is set to 0. A restart count 
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of 0 indicates that the port monitor is not to be restarted when it 
fails. 

COMMAND A string representing the conunand that will start the port mon- 
itor. The first component of the string, the command itself, 
must be a full patlmame. 



The Port Monitor Administrative Fiie pmtab 

Each port monitor will have two directories for its exclusive use. The current 
directory will contain files defined by the SAF (jpmtab, jpid) and the per- 
service configuration scripts, if they exist. The directory /var /saf /pmtag, 
where pmtag is the tag of the port monitor, is available for the port monitor's 
private files. 

Each port monitor has its own administrative file. The proadm command should 
be used to add, remove, or modify service entries in this file. Each time a 
change is made using pmaditv the corresponding port monitor rereads its admin- 
istrative file. Each entry in a port monitor's administrative file defines how the 
port monitor treats a specific port and what service is to be invoked on that 
port. 

Some fields must be present for all types of port monitors. Each entry must 
include a service tag to identify the service uniquely and an identity to be 
assigned to the service when it is started (for example, root). 



NOTE 



The combination of a service tag and a port monitor tag uniquely define an 
instance of a service. The same service tag may be used to identify a ser- 
vice under a different port monitor. 



The record must also contain port monitor specific data (for example, for a 
ttymon port monitor, this will include the prompt string which is meaningful to 
ttymon). Each type of port monitor must provide a command that takes the 
necessary port monitor-specific data as arguments and outputs these data in a 
form suitable for storage in the file. The ttyadni(lM) command does this for 
ttymon and nlsadmin(lM) does it for listen. For a user-defined port monitor, 
a similar administrative command must also be supplied. 
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Each service entry in the port monitor administrative file must have the follow- 
ing format and contain the information listed below: 

svctag : figs : id : reseirved : reserved : reserved : pmspecifict comment 

SVCTAG A unique tag that identifies a service. This tag is unique only 

for the port monitor through which the service is available. 
Other port monitors may offer the same or other services with 
the same tag. A service requires both a port monitor tag and a 
service tag to identify it uniquely. 

SVCTAG may consist of up to 14 alphanumeric characters. 

PLCS Hags with the following meanings may currently be included in 

this field: 

X Do not enable this port. 

By default the port is enabled. 

u Create a utinp entry for this service. 

By default no utrop entry is created for the service. 

Note that port monitors may ignore the u flag if creating a utnp 
entry for the service is not appropriate to the manner in which 
the service is to be invoked. Some services may not start prop- 
erly unless utnp entries have been created for them (for exam- 
ple, login). 

ID The identity under which the service is to be started. The iden- 

tity has the form of a login name as it appears in /etc/passwd. 

PMSPECIHC Examples of port monitor-specific information are addresses, the 
name of a process to execute, or the name of a STREAMS pipe to 
pass a connection through. This information will vary to meet 
the needs of each different type of port monitor. 

COMMENT A comment associated with the service entry. 



13-14 



Programmer's Guide: Networicing interfaces 



The Port Monitor Administrative interface 



~| Each port monitor administrative file must contain one special comment of 
NOTE the form: 

^^''^^ # VERSION-tw/we 

where value is an integer that represents the port monitor's version number. 
The version number defines the format of the port monitor administrative file. 
This comment line is created automatically when a port monitor is added to 
the system. It appears on a line by itself, before the service entries. 



The SAC Administrative Command sacadm 

sacadm is the administrative command for the upper level of the Service Access 
Facility hierarchy, that is, for pott monitor administration (see the sacadn<lM) 
manual page and the "Service Access" chapter of the System Administrator's 
Guide). Under the Service Access Facility, port monitors are administered by 
using the sacadm command to make changes in the SAC's administrative file, 
sacadm performs the functions listed below. 

■ print requested port monitor information from the SAC administrative file 

■ add or remove a port monitor 

■ enable or disable a port monitor 

■ start or stop a port monitor 

■ install or replace a per-system configuration script 

■ install or replace a per-port monitor configuration script 

■ ask the SAC to reread its administrative file 
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The Port Monitor Administrative Command pmadm 

pmdm is the administrative command for the lower level of the Service Access 
Facility hierarchy, that is, for service administration (see the manual page 
pmadnKlM) and the "Service Access" chapter of the System Administrator's 
Guide). A port may have only one service associated with it although the same 
service may be available through more than one port, pnadm performs the fol- 
lowing functions: 

■ print service status information from the port monitor's administrative file 

■ add or remove a service 

■ enable or disable a service 

■ install or replace a per-service configuration script 

Note that in order to identify an instance of a service uniquely, the pmadm com- 
mand must identify both the service (-s) and the port monitor or port monitors 
through which the service is available (-p or -t). 

A Port Monitor's "Port Monitor-Specific" 
Administrative Command 

In the previous section, two pieces of information included in the _pmtab file 
were described: the port monitor's version number and the port monitor-specific 
part of the service entries in the port monitor's __pmtab file. When a new port 
monitor is added, the version number must be known so that the jpmtab file 
can be correctly initialized. When a new service is added, the port monitor- 
specific part of the _pmtab entry must be formatted correctly. 

Each port monitor must have an administrative command to perform these two 
tasks. The person who defines the port monitor must also define such an 
administrative command and its input options. When the command is invoked 
with these options, the information required for the port monitor-specific part of 
the service entry must be correctly formatted for inclusion in the port monitor's 
jpratab file and must be written to the standard output. To request the version 
number the command must be invoked with a -V option; when it is invoked in 
this way, the port monitor's current version number must be written to the stan- 
dard output. 
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If the command fails for any reason during the execution of either of these 
tasks, nothing should be written to standard output. 

The Port Monitor/Service Interface 

The interface between a port monitor and a service is determined solely by the 
service. Two mechanisms for invoking a service will be presented here as exam- 
ples. 

New Service Invocations 

The first interface is for services that are started anew with each request. This 
interface requires the port monitor to first fork (2) a child process. The child 
will eventually become the designated service by performing an exec (2) . 
Before the exec (2) happens, the port monitor may take some port monitor- 
specific action; however, one action that must occur is the interpretation of the 
per-service configuration script, if one is present. This is done by calling the 
library routine doconfig(3N) . 

Standing Service invocations 

The second interface is for invocations of services that are actively running. To 
use this interface, a service must have one end of a stream pipe open and be 
prepared to receive connections through it. 
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To implement a port monitor, several generic requirements must be met. This 
section summarizes these requirements. In addition to the port monitor itself, 
an administrative command must be supplied. 

Initial Environment 

When a port monitor is started, it expects an initial execution environment in 
which: 

■ it will have no file descriptors open 

■ it will not be a process group leader 

■ it will have an entry in /etc/utnip of type LOGINJPROCESS 

■ an environment variable, ISTATE, will be set to "enabled" or "disabled" 
to indicate the port monitor's correct initial state 

■ an environment variable, PMTAG, will be set to the port monitor's assigned 
tag 

■ the directory that contains the port monitor's administrative files will be 
its current directoiy 

■ the port monitor will be able to create private files in the directory 
/var/saf /fag, where tag is the port monitor's tag 

■ the port monitor will be running with user id 0 (root) 



Important Files 

Relative to its current directory, the following key files exist for a port monitor: 

_conf ig The port monitor's configuration script. The port monitor 

configuration script is run by the Service Access Controller. The 
Service Access Controller is started by init(lM) as a result of 
an entry in /etc/inittab that calls sac(lM). 

jpid The file into which the port monitor writes its process id. 
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jpmtab The port monitor's administrative file. This file contains infor- 

mation about the ports and services for which the port monitor 
is responsible. 

jpinpipe The FIFO through which the port monitor will receive messages 

from the sac. 

svctag The per-service configuration script for the service with the tag 

svctag. 

. . /_sacpipe The FIFO through which the port monitor will send messages to 
the sac. 



Responsibilities 

A port monitor is responsible for performing the tasks described below in addi- 
tion to its port monitor-specific function. 

Miscellaneous Tasks 

A port monitor must perform the following miscellaneous tasks during its nor- 
mal operation: 

■ Write its process id into the file _j>id and place an advisory lock on the 

file. 

■ Terminate gracefully on receipt of the signal SIGTERM. 

■ Follow the protocol for message exchange with the sac. 

Service Related Tasks 

A port monitor must perform the following tasks during service invocation: 

■ Create a uturp entry if the requested service has the "u" flag set in 
_pnitab. 
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NOTE 



Port monitors may ignore this flag if creating a utnp entry for the ser- 
vice does not make sense because of the manner in which the ser- 
vice is to be invoked. On the other hand, some services may not 
start properly unless utnp entries have been created for them. 

Interpret the per-service configuration script for the requested service, if it 
exists, by calling the doconf ig (3N) library routine. 
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Configuration Files 

The Per-System Configuration File 

The per-system configuration file, /etc/saf /_sysconf ig, is delivered empty. It 
may be used to customize the environment for all services on the system by 
writing a command script in the interpreted language described in this chapter 
and on the doconf ig(3N) manual page. When the SAC is started, it calls the 
doconfigO function to interpret the per-system configuration script. The SAC 
is started when the system enters multi-user mode. 

Per-Port Monitor Configuration Fiies 

Per-port monitor configuration scripts (/etc/saf /pmtog/_conf ig) are optional. 
They allow the user to customize the environment for any given port monitor 
and for the services that are available through the ports for which that port 
monitor is responsible. Per-p>ort monitor configuration scripts are written in the 
same language used for per-system configuration scripts. 

The per-port monitor configuration script is interpreted when the port monitor 
is started. The p)ort monitor is started by the Service Access Controller after the 
SAC has itself been started and after it has run its own configuration script, 
/etc/saf/jsysconfig. 

The per-port monitor configuration script may override defaults provided by 
the per-system configuration script. 

Per-Service Configuration Files 

Per-service configuration files allow the user to customize the environment for a 
specific service. For example, a service may require special privileges that are 
not available to the general user. Using the language described in the 
doconf ig(3N) manual page, the programmer can write a script that will grant 
or limit such special privileges to a particular service offered through a particu- 
lar port monitor. 

The per-service configuration may override defaults provided by higher-level 
configuration scripts. For example, the per-service configuration script may 
specify a set of STREAMS modules other than the default set. 
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The Configuration Language 

The language in which configuration scripts are written consists of a sequence of 
commands, each of which is interpreted separately. The following reserved key- 
words are defined: assign, push, pop, runwait, and run. The comment char- 
acter is #. Blank lines are not significant. No line in a conunand script may 
exceed 1024 characters. 

assign variable=value 

Used to define environment variables, variable is the name of the 
environment variable and value is the value to be assigned to it. The 
value assigned must be a string constant; no form of parameter substitu- 
tion is available, value may be quoted. The quoting rules are those 
used by the shell for defining environment variables, assign will fail if 
space cannot be allocated for the new variable or if any part of the 
specification is invalid. 

push modulel[, module!, moduleS, . . .] 

Used to push STREAMS modules onto the stream designated by fd (see 
doconf ig<3N)). modulel is the name of the first module to be pushed, 
module! is the name of the second module to be pushed, etc. The com- 
mand will fail if any of the named modules cannot be pushed. If a 
module cannot be pushed, the subsequent modules on the same com- 
mand line will be ignored and modules that have already been pushed 
will be popped. 

pop [module] 

Used to pop STREAMS modules off the designated stream. If pop is 
invoked with no arguments, the top module on the stream is popped. If 
an argument is given, modules will be popped one at a time until the 
named module is at the top of the stream. If the named module is not 
on the designated stream, the stream is left as it was and the command 
fails. If module is the special keyword ALL, then all modules on the 
stream will be popped. Note that only modules above the topmost 
driver are affected. 

runwait command 

The runwait command runs a command and waits for it to complete. 
command is the pathname of the command to be run. The command is 
run with /bin/sh -c prepended to it; shell scripts may thus be exe- 
cuted from configuration scripts. The runwait command will fail if 
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command cannot be found or cannot be executed, or if command exits 
with a non-zero status. 

run command 

The run conunand is identical to runwait except that it does not wait 
for command to complete, command is the pathname of the command to 
be run. run will not fail unless it is unable to create a child process to 
execute the command. 

Although they are syntactically indistinguishable, some of the commands avail- 
able to run and runwait are interpreter built-in conunands. Interpreter built-ins 
are used when it is necessary to alter the state of a process within the context of 
that process. The dooonf ig interpreter built-in commands are similar to the 
shell special commands and, like these, they do not spawn another process for 
execution. See sh(l). The initial set of built-in commands is: 

cd 

ulimit 
unask 



Printing, Installing, and Replacing Configuration 
Scripts 

This section describes the form of the SAC and port monitor administrative com- 
mands used to install the three types of configuration scripts. Per-system and 
per-port monitor configuration scripts are administered using the sacadm com- 
mand. Per-service configuration scripts are administered using the pmdm com- 
mand. 

Per-System Configuration Scripts 

sacadm -G [ -z script ] 

The -G option is used to print or replace the per-system configuration script. 
The -G option by itself prints the per-system configuration script. The -G option 
in combination with a -z option replaces /etc/saf /__sysconf ig with the con- 
tents of the file script Other combinations of options with a -G option are 
invalid. 
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Per-Port Monitor Configuration Scripts 

sacadm -g -p pmtag [ -z script ] 

The -g option is used to print, install, or replace the per-port monitor 
configuration script. A -g option requires a -p option. The -g option with only 
a -p option prints the per-port nnonitor configuration script for port monitor 
pmtag. The -g option with a -p option and a -z option installs the file script as 
the per-port monitor configuration script for port monitor pmtag, or, if 
/etc/saf /pmfag/_conf ig exists, it replaces _conf ig with the contents of script. 
Other combinations of options with -g are invalid. 

Per-Service Configuration Scripts 

proadxn -g -p pmtag -s svctag [ -z script ] 
pnadm -g -s svctag -t type -z script 

Per-service configuration scripts are interpreted by the port monitor before the 
service is invoked. 



NOTE 



The SAC interprets both Its own configuration file, jsysconf ig, and the port 
monitor configuration files. Only the per-service configuration files are Inter- 
preted by the port monitors. 



The -g option is used to print, install, or replace a per-service configuration 
script. The -g option with a -p option and a -s option prints the per-service 
configuration script for service svctag available through port monitor pmtag. The 
-g option with a -p option, a -s option, and a -z option installs the per-service 
configuration script contained in the file script as the per-service configuration 
script for service svctag available through port monitor pmtag. The -g option 
with a -s option, a -t option, and a -z option installs the file script as the per- 
service configuration script for service svctag available through any port monitor 
of type type. Other combinations of options with -g are invalid. 
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Interpreting Configuration Scripts: doconfig() 

The library routine doconf ig ( ) , defined in libnsl . so, interprets the 
configuration scripts contained in the files /etc/saf /pmteg/__sysconf ig (the 
per-system configuration file), and /etc/saf /_conf ig (per-port monitor 
configuration files); and in /etc/ saf/pmtag/svctag (per-service configuration 
files). Its syntax is: 

# include <sac.h> 

int doconfig (int fd, char *script, long rflag) ; 

script is the name of the configuration script; fd is a file descriptor that desig- 
nates the stream to which stream manipulation operations are to be applied; 
rflag is a bitmask that indicates the mode in which script is to be interpreted. 
rflag may take two values, NORUN and NOASSIGN, which may be or'd. If rflag 
is zero, all commands in the configuration script are eligible to be interpreted. 
If rflag has the NOASSIGN bit set, the assign command is considered illegal and 
will generate an error return. If rflag has the NORUN bit set, the run and 
runwait commands are considered illegal and will generate error returns. 

If a command in the script fails, the interpretation of the script ceases at that 
point and a positive integer is returned; this number indicates which line in the 
script failed. If a system error occurs, a value of -1 is returned. 

If a script fails, the process whose environment was being established should not 
be started. 

In the example, doconfig () is used to interpret a per-service configuration 
script. 

mmmk.:z:: m^Mm \mitmtmisiik 



it id m doconfig (fd, avctag, Q)> 0) { 

error ( "doconf Ag faUed on lim^ %d of script i, jjvctag); 
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Sample Configuration Scripts 
Sample Per-System Configuration Script 

The __sysconf ig file in the example sets the time zone variable, TZ. 



ftaalcpi # set TZ 

xtinwalt edho ^ is starting > /ddv/<:K)nsol^ 



Sample Per-Port Monitor Configuration Script 

In the hypothetical _conf ig file in the figure, the command 
/usr/bin/daemon is assumed to start a daemon process that builds and holds 
together a STREAMS multiplexor. By installing this configuration script, the 
command can be executed just before starting the port monitor that requires it. 







^ 


« bqild a STEffiftKS multiplexor 






tm /ladr/bln/daemoa 






zunwait echo $PMrAG is starting > 


/dev/<x)nsole 




V. , 




J 



Sample Per-Servlce Configuration Script 

The following per-service configuration script does two things: It specifies the 
maximum file size for files created by a process by setting the process's ulimit 
to 4096. It also specifies the protection mask to be applied to files created by 
the process by setting umask to 077. 



r 



xmmlt laXiittit 4096 
runwait lanask 077 
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The following is an example of a "null" port monitor which does nothing 
except respond to messages from the Service Access Controller (sac). 



f include <dtdi0.te^ 

# Include <fetttX.h> 
I include <si9nal.h> 

# Andud© <3ac,h> 

char *get;env(); 

char Scratch JBUFSIZ3; /* acratdl buffer */ 

char TaglPMTAGSIZE] ; /* port monitor' 5 tag */ 

FILE *Fp; /* file pointer for log file */ 

Fli£ *Tfp/ /* file pointer for pldt file *f 

Char State; /* port monitor' 3 current state */ 



main(argc^ argv> 
int azgc; 
char *argvn; 

char *istate; 

strfijSytTag, getenvC'iWTAe*')); 



* <^>en up a log file in port monitor's private directory 



sprintf (Scratch, "/var/safAs/log", Tag); 
Pp - f open (Scratch, "a4*>; 
if (Fp — NOIi) 

exit(l); 
log(Fp, *• starting"); 

/* 

* retrieve initial state (either •♦enabled" or ♦•disabled*') and set 

* l^tate accordingly 

istate » getenv('»ISTATE">; 

sprlntf (Scratch, "IsmTE is %s**, istate); 

log(Fp, Scratch); 

If (Istrcmp (istate, "enabled**)) 

State ^ m wmmi 

V ) 

(continued on next page ) 
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St^te « PMJ)ZSA6LED; 

else { 

aog(£1c>i^ ^Invalid Initial state**); 
exita); 

ffprintf (Scxatdi, "PMTAG is ^s**, tag); 
1q9{F^, Scratch); 

* set up pia file and iock it to indicate that we are active 



Tfp - fopenC'jpid", »%#»♦); 
if (Tf p ^ NDIX) ( 

log<5^, "couldn't open pld file'*); 

exitd); 

iiiiiiiiiiiiiii^iiiiiiiiiil 

if (lockf (fil^o<Tfp), F__TEST, 0) < 0) { 

log(Fp, •♦pid file already locked**); 
exitd); 

fprintf(tfp, "W, getpidO); 
rewind (Tf p) ; 

log<Fp^ •* locking file-); 

if (lockf (fileno<Tfp), tJJXK, 0) < 0) ( 

log(Pp, nock failed-); 

exit (1); 

iiiliiilillllllllll^ 

* handle poll messages from the sac. . .this function never returns 

handlepollO ; 
pause 0; 
f close (Tf p) ; 
fclose(F^); 



handlepoXK) 

int pfd; /* file descriptor for incoiming pipe */ 

int sfd; /* file descriptor for outgoing pipe */ 

struct «acmser sacmsg; /* incondng message */ 

^ 

(continued on next page) 
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stxuct ym»q pmuig; outgoing mesdag^ 

^ open pipe for Incoming neasages front the sac 

lllllllllllllllllllllli^^ 

If (pfd < 0) { 

Xog(Fp^ ^jwipipe open faUod*); 
eicltd); 



pipe for outgoing meaaages to the sac 



Bfd^ open(*../ aacplpe'*/ 0 i^^^iMMMi. 
If (sfd < 0) { 

log(B^^ "_3acplpe qpen failed"); 
e)tit(X); ^ 

* 9tart to ]:>uild a return message; we only support class 1 messages 

»trcpy(pninsg.pmjtag^ Tag>; 
piT«nflg.pin_si2e m 
|xiiDsg..pm_maxclass 1; 

* keep responding to messages from the sac 

for (;;) { 

if (read (pfd, ^sacmsg^ sizeof (sacmsgji) l« slzeof (sacmsg)) { 
log(Ep, '»^jinplpe read failed"); 

* detezvidne the message type and respond appropriately 

switch (sacmsg.sc_type) { 
case SC_STATU5; 

V J 

(continued on next page ) 
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Xog<Fp, *»<3ot SCJ3TAT0S m^SBage*)/ 
pwnsg .pwjtype * PM^STATUS; 
Pf»»3g,i5m^»tat© - Stftte; 

case SCJ30U3LE: 

/* not© internal state change below */ 
log(Fp, **Got SCJ5NABLE Tnessage*^); 

State - mjmBsm) 

pmna^.pin^statd *" State; 
break; 
case SCJDISABUS: 

note internal state change belQW */ 
Xog(Pp^ "<3ot SCJJISABLE fliessage''>; 
|)inii9g.pinjt::ype * PM^StATOS; 
State SH_piS&BiLED; 

pitiMig.pittjsrtate - State; 
break; 
case SC_REAM)B; 

/* if this were a fully functional port monitor */ 

/* it would read jpintab here and take */ 

/* appropriate action */ 

log<Fp^ "Got SC_READDB Tfiessage**) ; 

pwinsg .pnijtype « PM^STATUS; 

pwnsg .ptft_state - State; 

break; 

default; 

sprintf (Scratdi, *Got unknown unessage <%d>**, sacmsg.scjtype) ; 

log(Fp, Scratch); 

pmmsg .pmjtype » PM_UNKNOWN; 



pnmsg.pm^state * State; 
break; 



iiiiiiiiiiiiiiliiiiiiiiili^^ 

* send bade a response to the poll indicating current state 

if (write (sfd, &pninsg, sizeof (pitmsg)) I* si zeof (pmmsg) ) { 
log<Fp, "sanity response failed"); 



(continued on next page) 
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r 






■\ 


lllllllllllllllil 

* general logging function 
*/ 




aog(fp, wsg) 

char %nag; 
{ 

fprintf (fp 
Jflu»h(fp) 

\ 














V 






J 
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I defituai ZDLEN 4 
1 define SCTODC Oxtt 



/* length In bytes of a utirp id 

/* wiid character for utmp id» */ 

/* ]ttMcl»um let>s(th In byt^d for a poxt *(K>nitor tag */ 



* values for rflas^ ife ddtiotifigO 



# define HDASSIQit 
« define H09R»N 



0x1 



/i^ idon^t allow assign ti{)eration$ */ 

/* don't allonf CTH or rwwait <^raticns */ 



* message to SAC (header Only) . this header is forever fixed. Utie 

* size field (pit^size) defines the si^ of the data portion of the 

* »iessage, Vhi<di follows the header, the fom of this optional 

* data portion is defined strictly by the message type (pnutype) . 



struct 



pninsg { 
char 
unchar 
char 

Char 
int 



pm^state; 
pinjnaxclass; 

pRL.^agtPMrAQ5lZB + 13; 
piftjsize; 



type of message */ 
/* current state of port monitor 
/* max message class this 

port monitor landerstands */ 
/* port monitor's tag */ 
/* size of optional data portion */ 



* pa type valtaes 

# define mj^hWS 

# define EM UNKNOWN 



* pra_state values 



* Class X response 
# define EM STARTING 



/* Status response ♦/ 

/* an unknown message was received */ 



/* port monitor in starting state */ 



(continued on next page ) 
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# define PMjaJABIED 

# define PMDISAHLED 

# define PM stopping 



2 


/♦ port 


3 


port 


4 


/* port 



* message to port inonitor 



struct aacmsg ( 

Int sc_»iJSfe; 
char »c type; 



/* size of optional data portion ^/ 
/*. type of message */ 



* scjtype vaXtaes 

* These represent comnands that the SAC sends to a port monitor. These 

* coRinands are divided into ^'classes* for extensibility. Each subsequ^t 

* "class** is a superset of the previous *^classes** plus the new cownands 

* defined within that "class'** The header for all conmands is identical; 

* however, a ccmnand »ay be defined such that an optional data portion may 

* be sent in addition to the header. The format of this optional data piece 
^ is self -defining based on the coRinand. Important note: the first message 

* sent by the SAC will always be a class X message. The port monitor 

* response will indicate the maximum class that it is able to understand. 

* Another note is that port monitors should only respond to a message with 

* an equivalent class resp<:«ise (i.e. a class 1 comnand causes a class 1 

* response} . 



* Class 1 cownands (currently, there are only class 1 comnands) 

llliiliilliiliiiii 



# define SC^STATOS 1 
I define SCJENABIZ 2 

# define SCJ)lSftBLE a 

# define SC f^BADDB 4 



/* status request */ 
/* enable request */ 
/* disable request */ 
/* read pmtab request */ 



* *ermo' values for Safermo, note that Safermo is used by 

* both pmadm and saca<Jn and these values are shared betweeai 

* th^ 
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# define EJBADABiSS 


1 


/* bad args or 111-fonoed coMnand line */ 


# define fiJIOJ>RXV 


2 


/* user not privileged for operation */ 


# define e]WbrR 


3 


/* generic SAF error */ 


# define EjSYSEBR 


4 


/* system error */ 


# define EJIOEXIST 


5 


/♦ invalid flpeclflcation */ 


# define %jm 


« 




1 define ijfmsA 




/♦ f>0i5t 1j»{»it<Wr i* rtthttihejf V 


# (Mine 


8 


/♦ port monitor is not runaing */ 


# define BJSBOOVER 


9 


/* in xeeovery */ 



V . . J 



/ 
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The first figure below is a logical diagram of the Service Access Facility. The 
second figure is the corresponding directory structure diagram; the list follow- 
ing it describes each of the files and directories. 

Figure 13-1: Service Access Facility iogicai frameworlc. 



Service Access Facility 



Port Monitor 1 
Configuration 





Per-System 
Configuration 



Port Monitor 2 
Configuration 




Config 



1 



Port Monitor 3 
Configuration 
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Figure 13-2: Service Access Facility directory structure. 

/ 



etc var 
saf saf 



sysconfig_sactab pmtagl . . . pmtagN Jog pmtagl . . . pmtagN 



config _pmtab svctag config _pmtab svctag 



/etc/saf /_sysconf ig 
/etc/saf /_sactab 

/ etc/ saf /pmtag 
/etc/saf/pmteg/_config 

/etc/sat /pmtag/ jpmtah 
/etc/saf /pmtag/svctag 
/var/saf/_log 



The per-system configuration script. 

The sac's administrative file. Contains infomna- 
tion about the port monitors for which the SAC 
is responsible. 

The home directory for port monitor pmtag. 

The per-port monitor configuration script for 
port monitor pmtag. 

Port monitor pmtag's administrative file. Con- 
tains information about the services for which 
pmtag is responsible. 

The file in which the per-service configuration 
script for service svctag (available through port 
monitor pmtag) is placed. 

The SAC'S log file. 
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/ var/ sat /pmtag The directory for files created by port monitor 

pmtag, for example its log file. 
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T 

ttymon 13: 1 
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Manual Pages 



Appendix A contains all Section 3N (Network Programming) manual pages for 
UMX System V Release 4.0. Most of the manual pages correspond to the docu- 
ments in this volume: TLI and Sockets, RFC (including XDR, secure RPC, and 
RFC services), and Network Selection and Name-to- Address Mapping. Other 
manual pages related to network programming but not specific to the contents 
of the volume are also included, however. The documentation that corresponds 
to these manual pages appears in other parts of the document set, for example, 
in the Network User's and Administrator's Guide (TCP) or the System 
Administrator's Guide (listen). 
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Table of Contents 



1. Commands 

chkey(l) change user encryption key 

keylogin(l) decrypt and store secret key 

rpcgen(l) an RPC protocol compiler 

rusers(l) who's logged in on local machines 

ypcat(l) print values in a YP data base 

ypmatch(l) print the value of one or more keys from a YP map 

5T)which(l) return name of YP server or map master 

bootparamd(lM) boot parameter server 

domainname(lM) get/set name of current secure RPC domain 

inetd(lM) Internet services daemon 

keyserv(lM) server for storing public and private keys 

makedbm(lM) make a YP dbm file 

newkey(lM) create a new key in the publickey database 

pmadm(lM) port monitor administration 

rpcbind(lM) universal addresses to RPC program number mapper 

rpcinfo(lM) report RPC information 

rpcrusersddM) network username server 

rwall(lM) write to all users over a network 

rpc.rwalld(lM) network rwall server 

sac(lM) service access controller 

siacadm(lM) service access controller administration 

spray (IM) spray packets 

rpc.sprayd (IM) spray server 

ypinit(lM) ; ^ build and install YP database 

ypmake(lM) rebuild YP database 

yppoll(lM) return current version of a YP map at a YP server host 

yppush(lM) force propagation of a changed YP map 

ypserv, ypbind(lM) ; YP server and binder processes 

ypset(lM) point jrpbind at a particular server 

ypupdated(lM) server for changing YP information 

ypxfr(lM) transfer YP map from a YP server to host 
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3. Functions 

dbm(3) database subroutines 

select (3C) synchronous I/O multiplexing 

acceptON) accept a connection on a socket 

bind(3N) bind a name to a socket 

byteorderON) convert values between host and network byte order 

connect (3^D initiate a connection on a socket 

dial(3C) establish an outgoing terminal line connection 

doconfig(3N) execute a configuration script 

ethers (3N) Ethernet address mapping operations 

gethostent(3N) get network host entry 

getnetconfig(3N) get network configuration database entry 

getnetent(3ND get network entry 

getnetpath(3N) get /etc/netconfig entry corresponding to NETPATH component 

getpeername(3N) get name of connected peer 

getprotoent(3N) get protocol entry 

getservent(3N) get service entry 

getsockname(3ND get socket name 

getsockopt(3N) get and set options on sockets 

inet(3N) Internet address manipulation 

listen (3N) listen for connections on a socket 

netdir_getbyname(3N) generic transport name-to-address translation 

nlsgetcall(3N) get client's data passed via the listener 

nlsprovider(3N) get name of transport provider 

nlsrequest(3ND format and send listener service request message 

publickey(3N) retrieve public or secret key 

recv(3N) receive a message from a socket 

resolver(3N) resolver routines 

rexec(3N) return stream to a remote command 

rpc(3N) library routines for remote procedure calls 

rpc_ch\t_auth(3N) library routines for client side remote procedure call authentication 

rpc_clnt_calls(3N) library routines for client side calls 

rpc_clnt_create (3N) 

library routines for dealing with creation and manipulation of CLIENT handles 

rpc_svc__calls(3N) library routines for registering servers 

rpc_svc_create(3N) library routines for dealing with the creation of server handles 

rpc_svc_err (3N) library routines for server side remote procedure call errors 

rpc_svc_reg(3N) library routines for RPC servers 

rpc_xdr(3N) XDR library routines for remote procedure calls 
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rpcbind(3N) library routines for RPC bind service 

rusers(3N) return information about users on remote machines 

rwall(3N) write to specified remote machines 

secure_rpc(3N) library routines for secure remote procedure calls 

send(3N) send a message from a socket 

shutdown (3N) shut down part of a full-duplex connection 

socket (3N) create an endpoint for commimication 

socketpair(3N) create a pair of connected sockets 

spray(3N) scatter data in order to check the network 

t_accept(3N) accept a connect request 

t_alloc(3N) allocate a library structure 

t_bind(3N) bind an address to a transport endpoint 

tdose(3N) close a transport endpoint 

t_cormect(3N) establish a connection with another transport user 

t_error(3N) produce error message 

t_free(3N) free a library structure 

t_getinfo(3N) get protocol-specific service information 

t^etstate(3N) get the current state 

t_listen(3N) listen for a connect request 

tJook(3N) look at the current event on a transport endpoint 

t_open(3N) establish a transport endpoint 

t_optmgmt(3N) manage options for a transport endpoint 

t_rcv(3N) receive data or expedited data sent over a connection 

t_rcvconnect(3N) receive the confirmation from a connect request 

t_rcvdis(3N) retrieve information from disconnect 

t__rcvrel(3N) acknowledge receipt of an orderly release indication 

t_rcvudata(3N) receive a data unit 

t__rcvuderr(3N) receive a unit data error indication 

t_snd(3N) send data or expedited data over a connection 

t_snddis(3N) send user-initiated disconnect request 

t_sndrel(3N) initiate an orderly release 

t_sndudata(3N) send a data unit 

t_sync(3N) synchronize transport library 

t__unbind(3N) disable a transport endpoint 

xdr(3N) library routines for external data representation 

xdr_admin(3N) library routines for external data representation 

xdr jcomplex (3N) library routines for external data representation 

xdr_create(3N) library routines for external data representation stream creation 

xdr_simple(3N) library routines for external data representation 

ypclnt(3N) YP client interface 
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yp_update(3N) 



changes yp information 



4. File Formats 

hosts (4) host name data base 

netconfig(4) network configuration database 

publickey(4) public key database 

rpc(4) rpc program number data base 

ttydefs(4) file contains terminal line settings information for ttymon 

updaters(4) configuration file for YP updating 

)T?files(4) the YP database and directory structure 

5. Miscellaneous Facilities 

environ (5) user environment 



7. Special Files 



ICMP(7) Internet Control Message Protocol 

IP(7) Internet Protocol 

sockio(7) ioctls that operate directly on sockets 

TCP(7) Internet Transmission Control Protocol 

ticks (7) loopback transport providers 

UDP(7) Internet User Datagram Protocol 
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t_accept accept a connect request t_accept(3N) 

accept accept a connection on a socket accept(3N) 

socket accept accept a connection on a accept(3N) 

sacadm service access controller administration sacadm(lM) 

sac service access controller sac(lM) 

release indication t__rcvrel acknowledge receipt of an orderly t_rcvrel(3N) 

inet_netof, inet_ntoa Internet address manipulation /inet__lnaof, inet(3N) 

ethers Ethernet address mapping operations ethers(3N) 

t bind bind an address to a transport endpoint t_bind(3N) 

mapper rpcbind universal addresses to RPC program number rpcbind(lM) 

pmadm port monitor administration pmadm(lM) 

sacadm service access controller administration sacadm(lM) 

t_alloc allocate a library structure t_alloc(3N) 

secure^rpc: authdes_seccreate, authdes__getucred, getnetname,/ secure_rpc(3N) 

authdes_getucred,/ secure_rpc: authdes__seccreate, secure_rpc(3N) 

authsys_create,/ rpc_clnt_auth: auth_destroy, authnone_create, rpc_dnt_auth(3N) 

client side remote procedure call authentication /routines for rpc_clnt_auth(3N) 

rpc_clnt_auth: auth_destroy, authnone_create, authsys_create,/ rpc_dnt_auth(3N) 

auth__destroy, authnone__create, authsys__create,/ rpc_clnt_auth: rpc_dnt_auth(3N) 

/authnone__create, authsys_create, authsys_create_default library/ rpc_dnt_auth(3N) 

hosts host name data base hosts(4) 

rpc rpc program number data base rpc(4) 

ypcat print values in a YP data base ypcat(l) 

bind bind a name to a socket bind(3N) 

endpoint t_bind bind an address to a transport t_bind(3N) 

bind bind a name to a socket bind(3N) 

rpcb_unset library routines for RPC bind service /rpcb_set, rpcbind(3N) 

ypserv, ypbind YP server and binder processes ypserv(lM) 

bootparamd boot parameter server bootparamd(lM) 

bootparamd boot parameter server bootparamd(lM) 

ypinit build and install YP database ypinit(lM) 

values between host and network byte order /ntohl, ntohs convert byteorder(3N) 

ntohs convert values between host/ byteorder, htonl, htons, ntohl, byteorder(3N) 

for client side remote procedure call authentication /routines rpc_dnt_auth(3N) 

for server side remote procedure call errors /library routines rpc_svc_err(3N) 

routines for remote procedure calls rpc library rpc(3N) 

library routines for dient side calls /rpc_broadcast, rpc_call rpc_dnt_calls(3N) 

routines for remote procedure calls /xdr_replymsg XDR library rpc_xdr(3N) 

for secure remote procedure calls /library routines secure_rpc(3N) 

chkey change user encryption key chkey(l) 

yppush force propagation of a changed YP map yppush(lM) 

yp_update changes yp information yp_update(3N) 

ypupdated server for changing YP information ypupdated(lM) 

spray scatter data in order to check the network spray(3N) 

chkey change user encryption key chkey(l) 

with creation and manipulation of CLIENT handles /for dealing rpc_clnt_create(3N) 

yperr^string, ypprot_err YP client interface /yp_master, ypclnt(3N) 
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rpc_call library routines for client side calls /rpc_broadcast, rpc_clnt_calls(3N) 

/library routines for client side remote procedure call/ rpc_clnt_auth(3N) 

listener nlsgetcall get client's data passed via the nlsgetcall(3N) 

clnt^geterr,/ rpc_clnt_calls: dnt_call, clnt_freeres, rpc_clnt_calls(3N) 

dnt^destroy,/ rpc_clnt_create: cintjx)ntrol, dnt^create, rpc__chit_create(3N) 

rpc_clnt_create: dnt^control, dnt_create, dnt_destroyy rpc_clnt_create(3N) 

/clnt_control, dnt^create, clnt__destroy, clnt_dg^create,/ rpc_clnt_create(3N) 

/dnt_aeate, clnt_destroy, dntjdgjcreate, cint_pcreateerrory rpc_clnt_create(3N) 

rpc_clnt_calls: clnt call, clnt_freeres, clnt__geterr,/ rpc_clnt_calls(3N) 

/dnt^call, clnt_freeres, dnt_^eterr, dnt__permo,/ rpcjclntj:alls(3N) 

/dnt_destroy, dnt_dg_create, clnt_pcreateerror, clnt_raw_create,/ rpc_clnt_create(3N) 

/clnt freeres, dnt^geterr, dnt^permo, dnt__perror,/ rpc_clnt_calls(3N) 

/clnt_geterr, clnt_perrno, dnt_perror, clnt_spermo,/ rpc_clnt__calls(3N) 

clnt_dg_create, clnt_pcreateerror, dntj-aw^aeate,/ /clnt_destroy, rpc_clnt_create(3N) 

/clnt_pcreateerror, clnt_raw_create, clnt_spcreateerror,/ rpc_clnt_create(3N) 

/clnt_permo, clnt_perror, cint_spermo, dnt^sperror,/ rpc_clnt_calls(3N) 

/clnt_perror, clnt_sperrno, dnt^sperror, rpc_broadcast// rpc_clnt_calls(3N) 

clnt_vc_create/ /clnt_spcreateerror, clntjtli_create, dnt Jp_create, rpc_clnt_create(3N) 

library routines/ /dnt_tli_create, dnt_tp_create, clnt_vc_create rpc_clnt_create(3N) 

/dnt tli create, clnt tp create, dntjvc_create library routines for/ rpc_clnt_create(3N) 

t dose dose a transport endpoint t_dose(3N) 

rexec return stream to a remote command rexec(3N) 

socket create an endpoint for communication socket(3N) 

rpcgen an RPC protocol compiler rpcgen(l) 

entry corresponding to NETPATH component /get /etc/netconfig getnetpath(3N) 

getnetconfig get network configuration database entry getnetconfig(3N) 

netconfig network configuration database netconfig(4) 

updaters configuration file for YP updating updaters(4) 

doconfig execute a configuration script doconfig(3N) 

t jrcvconnect receive the confirmation from a connect request t jrcvconnect(3N) 

socket connect initiate a connection on a connect(3N) 

t_accept accept a connect request t_accept(3N) 

t listen listen for a connect request t_listen(3N) 

receive the confirmation from a connect request t_rcvconnect t_rcvconnect(3N) 

getpeemame get name of connected peer getpeemame(3N) 

socketpair aeate a pair of connected sockets socketpair(3N) 

establish an outgoing terminal line connection dial dial(30 

accept accept a connection on a socket accept(3N) 

connect initiate a connection on a socket connect(3N) 

shut down part of a full-duplex connection shutdown shutdown(3N) 

data or expedited data sent over a connection t rcv receive t_rcv(3N) 

send data or expedited data over a connection t snd t_snd(3N) 

user t_connect establish a connection with another transport t_connect(3N) 

listen listen for connections on a socket listen (3N) 

information for/ ttydefs file contains terminal line settings ttydefs(4) 

ICMP Internet Contirol Message Protocol ICMP(7) 

TCP Internet Transmission Control Protocol TCP(7) 
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sacadm service access controller administration sacadm(lM) 

sac service access controller sac(lM) 

network/ /htonl, htons, ntohl, ntohs convert values between host and byteorder(3N) 

getnetpath get /etc/netconfig entry corresponding to NETPATH component getnetpath(3N) 

database newkey create a new key in the publickey newkey(lM) 

socketpair create a pair of connected sockets socketpair(3N) 

commimication socket create an endpoint for socket(3N) 

/library routines for dealing with creation and manipulation of CLIENT/ 

rpc_clnt_create(3N) 

routines for dealing with the creation of server handles /library rpc_svc_create(3N) 

external data representation stream creation /library routines for xdr_create(3N) 

endpoint t Jook look at the current event on a transport tJook(3N) 

domainname get/set name of current secure RFC domain domainname(lM) 

t_getstate get the current state t _^etstate(3N) 

server host yppoll return current version of a YP map at a YP yppoll(lM) 

inetd Internet services daemon inetd(lM) 

hosts host name database hosts(4) 

rpc rpc program number data base rpc(4) 

ypcat print values in a YP data base ypcat(l) 

t_rcvuderr receive a unit data error indication t_rcvuderr(3N) 

spray scatter data in order to check the network spray(3N) 

connection t_snd send data or expedited data over a t_snd(3N) 

connection t_rcv receive data or expedited data sent over a tj:cv(3N) 

t_snd send data or expedited data over a connection t_snd(3N) 

nlsgetcall get client's data passed via the listener nlsgetcall(3N) 

/library routines for external data representation stream creation xdr_create(3N) 

xdr library routines for external data representation xdr(3N) 

library routines for external data representation /xdr setpos xdr_admin(3N) 

library routines for external data representation /xdr wrapstring xdr_complex(3N) 

library routines for external data representation /xdr void xdr_simple(3N) 

t_rcv receive data or expedited data sent over a connection t_rcv(3N) 

t jrcvudata receive a data imit t_rcvudata(3N) 

t_sndudata send a data unit t_sndudata(3N) 

ypfiles the YP database and directory structure ypfiles(4) 

get network configuration database entry getnetconfig getnetcon£Lg(3N) 

netconfig network configuration database netconfig(4) 

create a new key in the publickey database newkey newkey(lM) 

publickey public key database publickey(4) 

store, delete, firstkey, nextkey database subroutines /fetch, dbm(3) 

ypinit build and install YP database ypinit(lM) 

ypmake rebuild YP database ypmake(lM) 

UDP Internet User Datagram Protocol UDP(7) 

store, delete, firstkey, nextkey/ dbm, dbminit, dbmdose, fetch, dbm(3) 

makedbm make a YP dbm file makedbm(lM) 

firstkey, nextkey/ dbm, dbminit, dbmdose, fetch, store, delete, dbm(3) 

delete, firstkey, nextkey/ dbm, dbminit, dbmclose, fetch, store, dbm(3) 

/clnt_vc_create library routines for dealing with creation and/ rpc_clnt_create(3N) 
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/svc_vc_create library routines for dealing with the creation of server/ rpc_svc_create(3N) 

keylogin decrypt and store secret key keylogin(l) 

/dbminit, dbmdose, fetch, store, delete, firstkey, nextkey database/ dbm(3) 

line connection dial establish an outgoing terminal dial(3Q 

sockio ioctls that operate directly on sockets sockio(7) 

ypfiles the YP database and directory structure ypfiles(4) 

t_unbind disable a transport endpoint t_unbind(3N) 

t_snddis send user-initiated disconnect request t__snddis(3N) 

tjrcvdis retrieve information from disconnect t_rcvdis(3N) 

/res__mkquery, res_send, res_init, dn_comp, dn_expand resolver/ resolver(3N) 

/res_send, res_init, dn comp, dn expand resolver routines resolver(3N) 

script doconfig execute a configuration doconfig(3N) 

get/set name of current secure RPC domain domainname domainn>ame(lM) 

secure RPC domain domainname get/set name of current domainname(lM) 

chkey change user encryption key chkey(l) 

/gethostbyname, sethostent, endhostent get network host entry gethostent(3N) 

/getnetbyname, setnetent, endnetent get network entry getnetent(3N) 

socket create an endpoint for communication socket(3N) 

bind an address to a transport endpoint t_bind tJ)ind(3N) 

t_dose close a transport endpoint t_close(3N) 

at the current event on a transport endpoint t Jock look tJook(3N) 

t_open establish a transport endpoint t_open(3N) 

manage options for a transport endpoint t_optmgmt t_optmgmt(3N) 

t^imbind disable a transport endpoint t_vmbind(3N) 

/getprotobyname, setprotoent, endprotoent get protocol entry getprotoent(3N) 

/getservbyname, setservent, endservent get service entry getservent(3N) 

getnetpath get /etc/netconfig entry corresponding to NETPATH/ getnetpath(3N) 

endhostent get network host entry /gethostbyname, sethostent, gethostent(3N) 

get network configuration database entry getnetconfig getnetconfig(3N) 

setnetent, endnetent get network entry /getnetbyaddr, getnetbyname, getnetent(3N) 

endprotoent get protocol entry /getprotobyname, setprotoent, getprotoent(3N) 

setservent, endservent get service entry /getservbyname, getservent(3N) 

environ user environment environ(5) 

environ \iser environment environ(5) 

t_rcvuderr receive a unit data error indication tj:cvuderr(3N) 

t_error produce error message t_error(3N) 

server side remote procedure call errors /library routines for rpc_svc_err(3N) 

transport user t_connect establish a connection with another t_connect(3N) 

t_open establish a transport endpoint t_open(3N) 

connection dial establish an outgoing terminal line dial(3Q 

to NETPATH/ getnetpath get /etc/netconfig entry corresponding getnetpath(3N) 

ethers Ethernet address mapping operations ethers(3N) 

operations ethers Ethernet address mapping ethers(3N) 

tjook look at the current event on a transport endpoint tJook(3N) 

doconfig execute a configuration script doconfig(3N) 

t_snd send data or expedited data over a connection t_snd(3N) 

connection t_rcv receive data or expedited data sent over a t_rcv(3N) 
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creation /library routines for external data representation stream xdr_create(3N) 

xdr library routines for external data representation xdr(3N) 

/xdr_setpos library routines for external data representation xdr_admin(3N) 

/xdr_wrapstring library routines for external data representation xdr_complex(3N) 

/xdr void library routines for external data representation xdr_simple(3N) 

nextkey/ dbm, dbminit, dbmclose, fetch, store, delete, firstkey, dbm(3) 

settings information for/ ttydefs file contains terminal line ttydefs(4) 

updaters configuration file for YP updating updaters(4) 

makedbm make a YP dbm file makedbm(lM) 

/dbmdose, fetch, store, delete, firstkey, nextkey database/ dbm(3) 

map yppush force propagation of a changed YP yppush(lM) 

request message nlsrequest format and send listener service nlsrequest(3N) 

t_free free a library structtire t_free(3N) 

shutdown shut down part of a full-duplex connection shutdown(3N) 

/netdirj>error, netdir_sperror generic transport name-to-address/ 

netdir_getbyname(3N) 

sethostent, endhostent/ gethostent, gethostbyaddr, gethostbyname, gethostent(3N) 

getiiostent, getiiostbyaddr, getiiostbyname, sethostent,/ gethostent(3N) 

getiiostbyname, setiiostent,/ gethostent, gethostbyaddr, gethostent(3N) 

setnetent, endnetent/ getnetent, getnetbyaddr, getnetbyname, getnetent(3N) 

get/ getnetent, getnetbyaddr, getnetbyname, setnetent, endnetent getnetent(3N) 

configuration database entry getnetconfig get network getnetconfig(3N) 

getnetbyname, setnetent, endnetent/ getnetent, getnetbyaddr, getnetent(3N) 

/authdes _getucred, getnetname, host!^etname,/ secure_rpc(3N) 

corresponding to NETPATH component getnetpath get /etc/netconfig entry getnetpath(3N) 

peer getpeemame get name of connected getpeemame(3N) 

getprotoent, getprotobynimiber, getprotobyname, setprotoent,/ getprotoent(3N) 

setprotoent,/ getprotoent, getprotobynumber, getprotobyname, getprotoent(3N) 

getprotobyname, setprotoent,/ getprotoent, getprotobynimiber, getprotoent(3N) 

public or secret key publickey: getpublickey, getsecretkey retrieve publickey(3N) 

secret/ publickey: getpublickey, getsecretkey retrieve public or publickey(3N) 

getservent, getservbyport, getservbyname, setservent,/ getservent(3N) 

setservent, endservent/ getservent, getservbyport, getservbyname, getservent(3N) 

getservbyname, setservent,/ getservent, getservbyport, getservent(3N) 

domain domainname get/set name of current secure RPC domainname(lM) 

getsockname get socket name getsockname(3N) 

options on sockets g^tsockopt, setsockopt get and set getsockopt(3N) 

creation and manipidation of CLIENT handles /routines for dealing with rpc_clnt_create(3N) 

dealing with the creation of server handles /library routines for rpc_svc_create(3N) 

ntohl, ntohs convert values between host and network byte order /htons, byteorder(3N) 

sethostent, endhostent get network host entry /gethostbyname, gethostent(3N) 

hosts host name data base hosts(4) 

version of a YP map at a YP server host yppoll return current yppoll(lM) 

transfer YP map from a YP server to host )rpxfr ypxfr(lM) 

/authdes _^etucred, getnetname, host2netname, key_decryptsession,/ secure_rpc(3N) 

hosts host name data base hosts(4) 

values between host and/ byteorder, htonl, htons, ntohl, ntohs convert byteorder(3N) 
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between host and/ byteorder, htonl, htons, ntohl, ntohs convert values byteorder(3N) 

Protocol ICMP Internet Control Message ICMP(7) 

receipt of an orderly release indication t_rcvrel acknowledge t_rcvrel(3N) 

receive a unit data error indication t_rcvuderr tj-cvuderrCSN) 

inet_makeaddr, inetjnaot/ inet: inet_addr, inet network, inet(3N) 

inet_makeaddr, inetjnaof,/ inet: inet addr, inet_network, inet(3N) 

inetd Internet services daemon inetd(lM) 

/inetjietwork, inet_makeaddr, inetjnaof, inet_netof, inetjitoa/ inet(3N) 

inet: inet__addr, inet_network, inet_makeaddr, inetjnaof,/ inet(3N) 

address/ /inet makeaddr, inet_lnaof, inet^netot inet^ntoa Internet inet(3N) 

inet_lnaot/ inet: inet_addr, inet_network, inet_makeaddr, inet(3N) 

/inet Jnaof, inet_netof, inet_ntoa Internet address/ inet(3N) 

machines rusers return information about users on remote rusers(3N) 

contains terminal line settings information for ttymon /file ttydefs(4) 

t_rcvdis retrieve information from disconnect t_rcvdis(3N) 

rpdnfo report RPC information rpcinfo(lM) 

get protocol-specific service information tjgetinfo t_getinfo(3N) 

yp_update changes yp information yp_update(3N) 

3rpupdated server for changing YP information ypupdated(lM) 

connect initiate a connection on a socket connect(3N) 

t_sndrel initiate an orderly release t sndrel(3N) 

ypinit build and install YP database ypinit(lM) 

yperr string, ypprot err YP client interface /yp order, yp_master, ypclnt(3N) 

/inet_lnaof, inet_netot inet_ntoa Internet address manipulation inet(3N) 

ICMP Internet Control Message Protocol ICMP(7) 

IP Internet Protocol IP(7) 

inetd Internet services daemon inetd(lM) 

Protocol TCP Internet Transmission Control TCP(7) 

UDP Internet User Datagram Protocol UDP(7) 

select synchronous I/O multiplexing select(3Q 

sockets sockio ioctls that operate directly on sockio(7) 

IP Internet Protocol IP(7) 

chkey change user encryption key chkey(l) 

publickey public key database publickey(4) 

newkey create a new key in the publickey database newkey(lM) 

keylogin decr)rpt and store secret key keyloginCl) 

retrieve public or secret key /getpublickey, getsecretkey publickey(3N) 

/getnetname, host2netname, key_decryptsessionV secure_rpc(3N) 

/host2netname, key_decryptsession, key_encryptsession, key_gendes,/ secure_rpc(3N) 

netname2host,/ /key_encryptsession, key_gendes, key_setsecret, secure_rpc(3N) 

key keylogin decrypt and store secret keylogin(l) 

print the value of one or more keys from a YP map ypmatch , ypmatch(l) 

for storing public and private keys keyserv server keyserv(lM) 

and private keys keyserv server for storing public keyserv(lM) 

/key_encryptsession, key gendes, key setsecret, netname2host,/ secure_rpc(3N) 

calls /rpc_broadcast, rpcj:all library routines for client side rpc_clnt_calls(3N) 

remote/ /authsys_create_default library routines for client side rpc_clnt_auth(3N) 
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/clnt_tp_create, dnt vc create library routines for dealing with/ rpc_clnt_create(3N) 

the/ /svc_tp_create, svc vc create library routines for dealing with rpc_svc_create(3N) 

/xdrrec_create, xdrstdio_create library routines for external data/ xdr_create(3N) 

representation xdr library routines for external data xdr(3N) 

/xdr_inUne, xdrrec_eot xdr setpos library routines for external data/ xdr_admin(3N) 

/xdr vector, xdr wrapstring library routines for external data/ xdr_complex(3N) 

/xdr_uJong, xdr u short, xdr void library routines for external data/ xdr_simple(3N) 

/xprt register, xprt unregister library routines for registering/ rpc_svc_calls(3N) 

procedure calls rpc library routines for remote rpc(3N) 

procedure calls /xdr^replymsg XDR library routines for remote rpc_xdr(3N) 

/rpcb_rmtcall, rpcb^set, rpcb unset library routines for RPC bind/ rpcbind(3N) 

/svc_run, svc_sendreply library routines for RPC servers rpc_svc_reg(3N) 

/netname2user, user2netname library routines for secure remote/ secure_rpc(3N) 

/svcerr_systemerr, svcerr_weakauth library routines for server side/ rpc_svc_err(3N) 

t alloc allocate a library structure t_alloc(3N) 

t free free a library structure t_free(3N) 

t_sync synchronize transport library t_s)mc(3N) 

dial establish an outgoing terminal line connection dial(3Q 

ttydefs file contains terminal line settings information for/ ttydefs(4) 

t_listen listen for a connect request t_listen(3N) 

listen listen for connections on a socket listen(3N) 

socket listen listen for connections on a listen(3N) 

get client's data passed via the listener nlsgetcall nlsgetcall(3N) 

nlsrequest format and send listener service request message nlsrequest(3N) 

rusers who's logged in on local machines rusers(l) 

Risers who's logged in on local machines rusers(l) 

transport endpoint t look look at the current event on a tJook(3N) 

ticlts, ticots, ticotsord loopback transport providers tidts(7) 

rusers who's logged in on local machines rusers(l) 

information about users on remote machines rusers return rusers(3N) 

rwall write to specified remote machines rwall(3N) 

makedbm make a YP dbm file makedbm(lM) 

endpoint t optmgmt manage options for a transport t_optmgmt(3N) 

inet_ntoa Internet address manipulation /inet_netof, inet(3N) 

/for dealing with creation and manipulation of CLIENT handles rpc_clnt__create(3N) 

return current version of a YP map at a YP server host yppoll yppoll(lM) 

ypxfr transfer YP map from a YP server to host ypxfr(lM) 

ypwhich return name of YP server or map master ypwhich(l) 

value of one or more keys from a YP map ypmatch print the ypmatch(l) 

force propagation of a changed YP map yppush yppush(lM) 

addresses to RPC program nvimber mapper rpcbind universal rpcbind(lM) 

ethers Ethernet address mapping operations ethers(3N) 

return name of YP server or map master ypwhich ypwhich(l) 

recv, recvfrom, recvmsg receive a message from a socket recv(3N) 

send, sendto, sendmsg send a message from a socket send(3N) 

and send listener service request message nlsrequest format nlsrequest(3N) 

ICMP Internet Control Message Protocol ICMP(7) 
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t_error produce error message t__error(3N) 

pmadm port monitor administration pmadm(lM) 

select synchronous I/O multiplexing select(3Q 

hosts host name data base hosts(4) 

getsockname get socket name getsockname(3N) 

getpeername get name of connected peer getpeemame(3N) 

domainname get/ set name of current secure RPC domain domainname(lM) 

nlsprovider get name of transport provider nlsprovider(3N) 

ypwhich rettun name of YP server or map master ypwhich(l) 

bind bind a name to a socket bind(3N) 

/netdir_sperror generic transport name-to-address translation netdir_getbyname(3N) 

database netconfig network configuration netconfig(4) 

netdir getbyname, netdir getbyaddr, netdir_free^ netdirjnergeaddr^ netdir_getbyname(3N) 

netdir^getbyname, netdir^^etbyaddr, netdir_free,/ netdir^etb5mame(3N) 

netdir_free, netdir_mergeaddr,/ netdir_getbyname, netdir_getbyaddr^ 

netdir_getbyname(3N) 

/netdir getbyaddr, netdir free, netdirjmergeaddr, taddr2uaddr,/ netdir_getbyname(3N) 

generic/ /taddr2uaddr, uaddr2taddr, netdir_j>error, netdir_sperror netdir_getbyname(3N) 

/uaddr2taddr, netdir__perror, netdir_sperror generic transport/ netdir_getbyname(3N) 

/key _gendes, key_setsecret, netname2host netname2user,/ secure_rpc(3N) 

/key_setsecret, netname2host, netname2user, user2netname library/ secure_rpc(3N) 

entry corresponding to NETPATH component //etc/netoonfig getnetpath(3N) 

convert values between host and network byte order /ntohl, ntohs byteorder(3N) 

entry getnetconfig get network configuration database getnetconfig(3N) 

netconfig network configuration database netconfig(4) 

setnetent, endnetent get network entry /getnetbyname, getnetent(3N) 

sethostent endhostent get network host entry /gethostbyname, gethostent(3N) 

rpcrwalld network rwall server rpc.rwalld(lM) 

rwall write to all users over a network rwaU(lM) 

scatter data in order to check the network spray spray(3N) 

rpcrusersd network username server rpc.rusersd(lM) 

publickey database newkey create a new key in the newkey(lM) 

/fetch, store, delete, firstkey, nextkey database subroutines dbm(3) 

via the listener nlsgetcall get client's data passed nlsgetcall(3N) 

provider nlsprovider get name of transport nlsprovider(3N) 

service request message nlsrequest format and send listener ni5request(3N) 

host and/ byteorder, htonl, htons, ntohl, ntohs convert values between byteorder(3N) 

byteorder, htonl, htons, ntohl, ntohs convert values between host/ byteorder(3N) 

rpc rpc program nimiber data base rpc(4) 

universal addresses to RPC program nimiber mapper rpcbind rpcbind(lM) 

sockio ioctls that operate directly on sockets sockio(7) 

ethers Ethernet address mapping operations ethers(3N) 

t optmgmt manage options for a transport endpoint t_optmgmt(3N) 

getsockopt, setsockopt get and set options on sockets getsockopt(3N) 

between host and network byte order /ntohl, ntohs convert values byteorder(3N) 

spray scatter data in order to check the network spray(3N) 

t rcvrd acknowledge receipt of an orderly release indication t j-cvrel(3N) 
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t_sndrel initiate an orderly release t_sndrel(3N) 

dial establish an outgoing terminal line connection dial(3Q 

spray spray packets spray(lM) 

socketpair create a pair of connected sockets socketpair(3N) 

bootparamd boot parameter server bootparamd(lM) 

shutdown shut down part of a full-duplex connection shutdown(3N) 

ypset point ypbind at a particular server ypset(lM) 

nlsgetcall get dient's data passed via the listener nlsgetcall(3N) 

getpeemame get name of connected peer getpeemame(3N) 

pmadm port monitor administration pmadm(lM) 

ypset point ypbind at a particular server ypset(lM) 

pmadm port monitor administration pmadm(lM) 

from a YP map ypmatch print the value of one or more kejrs ypmatch(l) 

ypcat print values in a YP data base ypcat(l) 

server for storing public and private keys keyserv keyserv(lM) 

/routines for client side remote procedure call authentication rpc_dnt_auth(3N) 

routmes for server side remote procedure call errors /library rpc_svc_err(3N) 

rpc library routines for remote procedure calls rpc(3N) 

XDR library routines for remote procedure calls /xdr jreplymsg rpc_xdr(3N) 

library routines for secure remote procedure calls /user2netname secure_rpc(3N) 

ypserv, ypbind YP server and binder processes ypserv(lM) 

t_error produce error message t_error(3N) 

rpc rpc program nimiber data base rpc(4) 

rpcbind universal addresses to RPC program nvmiber mapper rpcbind(lM) 

yppush force propagation of a changed YP map yppush(lM) 

rpcgen an RPC protocol compiler rpcgen(l) 

setprotoent, endprotoent get protocol entry /getprotobyname, getprotoent(3N) 

ICMP Internet Control Message Protocol ICMP(7) 

IP Internet Protocol IP(7) 

TCP Internet Transmission Control Protocol TCP(7) 

UDP Internet User Datagram Protocol UDP(7) 

information t^etinfoget protocol-specific service t _getinfo(3N) 

nlsprovider get name of transport provider nlsprovider(3N) 

ticotsord loopback transport providers ticlts, ticots, tidts(7) 

keyserv server for storing public and private keys keyserv(lM) 

publickey public key database publickey(4) 

getpubUdcey, getsecretkey retrieve public or secret key publickey: publickey(3N) 

newkey create a new key in the publickey database newkey(lM) 

getsecretkey retrieve public or/ publickey: getpublickey, publickey(3N) 

publickey public key database publickey(4) 

ypmake rebuild YP database ypmake(lM) 

indication t_rcvrel acknowledge receipt of an orderly release t_rcvrel(3N) 

t_rcvudata receive a data rmit t_rcvudata(3N) 

recv, recvfrom, recvmsg receive a message from a socket recv(3N) 

indication t_rcvuderr receive a vmit data error tj:cvuderr(3N) 

over a connection t_rcv receive data or expedited data sent tj:cv(3N) 

connect request t jrcvconnect receive the confirmation from a t_rcvconnect(3N) 
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message from a socket recv, recvfrom, recvmsg receive a recv(3N) 

from a socket recv, recvfrom, recvmsg receive a message recv(3N) 

socket recv, recvfrom, recvmsg receive a message from a recv(3N) 

/library routines for registering servers rpc_svcjcalls(3N) 

acknowledge receipt of an orderly release indication tj-cvrel tj'cvrel(3N) 

t_sndrel initiate an orderly release t_sndrel(3N) 

rexec return stream to a remote command rexec(3N) 

return information about users on remote machines rusers rusers(3N) 

rwall write to specified remote machines rwall(3N) 

/library routines for client side remote procedure call/ rpc_clnt_auth(3N) 

/library routines for server side remote procedure call errors rpc_svc_err(3N) 

rpc library routines for remote procedure calls rpc(3N) 

/XDR library routines for remote procedure calls rpc__xdr(3N) 

/library routines for secure remote procedure calls secure_rpc(3N) 

rpdnfo report RPC information rpcinfo(lM) 

/library routines for external data representation stream creation xdr_create(3N) 

library routines for external data representation xdr xdr(3N) 

library routines for external data representation /xdr setpos xdr_admin(3N) 

library routines for external data representation /xdr wrapstring xdr_complex(3N) 

library routines for external data representation /xdr void xdr_simple(3N) 

format and send listener service request message nlsrequest nlsrequest(3N) 

t accept accept a connect request t_accept(3N) 

t listen listen for a connect request t_listen(3N) 

the confirmation from a connect request t rcvconnect receive t_rcvconnect(3N) 

send user-initiated disconnect request t snddis t_snddis(3N) 

resolver, res mkquery, res_send, res init, dn comp, dn expand/ resolver(3N) 

dn comp, dn expand/ resolver, res mkquery, res send, resjnit, resolver(3N) 

res init, dn comp, dn expand/ resolver, res mkquery, res_send, resolver(3N) 

res init, dn comp, dn expand resolver routines /res send, resolver(3N) 

dn_expand/ resolver, res mkquery, res send, res init, dn_comp, resolver(3N) 

disconnect t_rcvdis retrieve information from t_rcvdis(3N) 

/getpublickey, getsecretkey retrieve public or secret key publickey(3N) 

at a YP server host yppoll return current version of a YP map yppoU(lM) 

remote machines rusers return information about users on rusers(3N) 

master ypwhich return name of YP server or map ypwhich(l) 

rexec return stream to a remote command rexec(3N) 

command rexec return stream to a remote rexec(3N) 

/rpc_broadcast, rpc_call library routines for client side calls rpc_clnt_calls(3N) 

/authsys_create_default library routines for client side remote/ rpc_clnt_auth(3N) 

and/ /clnt__vc_create library routines for dealing with creation rpc_dnt_create(3N) 

creation of/ /svcjvc_create library routines for dealing with the rpc_svc_create(3N) 

/xdrstdio_create library routines for external data/ xdr_create(3N) 

representation xdr library routines for external data xdr(3N) 

/xdrrec_eof, xdr_setpos library routines for external data/ xdr_admin(3N) 

/xdr vector, xdr wrapstring library routines for external data/ xdr_complex(3N) 

/xdr_u_short, xdr_void library routines for external data/ xdr_simple(3N) 

/xprtjmregister library routines for registering servers rpc_svc_calls(3N) 
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rpc library routines for remote procedure calls rpc(3N) 

/xdr_replymsg XDR library routines for remote procedure calls rpc_xdr(3N) 

/rpcb_set, rpcbjinset library routines for RPC bind service rpcbind(3N) 

/svcjrun, svc_sendreply library routines for RPC servers rpc_svc_reg(3N) 

/netname2user, user2netname library routines for secure remote/ secure_rpc(3N) 

procedure/ /svcerr weakauth library routines for server side remote rpc_svc_err(3N) 

dn_comp, dn_expand resolver routines /res_send, res init, resolver(3N) 

rpcb_unset library routines for RPC bind service /rpcb_set, rpcbind(3N) 

get/set name of current secure RPC domain domainname domainname(lM) 

rpdnfo report RPC information rpcinfo(lM) 

procedure calls rpc library routines for remote rpc(3N) 

rpc rpc program number data base rpc(4) 

rpcbind tmiversal addresses to RPC program number mapper rpcbind(lM) 

rpcgen an RPC protocol compiler rpcgen(l) 

rpc rpc program number data base rpc(4) 

svc_sendreply library routines for RPC servers /svc rim, rpc_svc_reg(3N) 

rpcbind: rpcb getmaps, rpcb getaddr, rpcb gettime,/ rpcbind(3N) 

rpcb_^ettime,/ rpcbind: rfxrb getmaps, rpcb^etaddr, rpcbind(3N) 

/rpcb^etmaps, rpcb^^etaddr, rpcb_gettime, rpcb_rmtcall,/ rpcbind(3N) 

rpcb getaddr, rpcb^ettime,/ rpcbind: rpcb^etmaps, rpcbind(3N) 

program nimiber mapper rpcbind imiversal addresses to RPC rpcbind(lM) 

/rpcb_getaddr, rpcb gettime, rpcb^rmtcaU, rpcb set, rpcbjinset/ rpcbind(3N) 

/clnt_spermo, clnt_sperror, rpc_broadcast, rpc_call library/ rpc_dnt_calls(3N) 

/rpcb gettime, rpcb rmtcall, rpcb_set, rpcb imset library/ rpcbind(3N) 

bind/ /rpcb_rmtcall, rpcb set, rpcb_tmset library routines for RPC rpcbind(3N) 

/dnt_sperror, rpc broadcast, rpc_call library routines for/ rpc_dnt_calls(3N) 

authnone_create, authsys create,/ rpc_clnt_auth: auth destroy, rpc_dnt_auth(3N) 

dnt^freeres, dnt_geterr,/ rpc_clnt_calls: dnt call, rpc_clnt_calls(3N) 

clnt_create, clnt_destroy,/ rpc_clnt_create: dnt_control, rpc_clnt_create(3N) 

rpcgen an RPC protocol compiler rpcgen(l) 

rpdnfo report KPC information rpcinfo(lM) 

xprtjregister,/ rpc_svc_calls: rpcjreg, svc__reg, svc^unreg, rpcjsvc_calls(3N) 

rpcrusersd network usemame server rpc.rusersd(lM) 

rpcrwalld network rwall server rpc.rwalld(lM) 

rpcsprayd spray server rpc.sprayd(lM) 

svc^imreg, xprt register,/ rpc_svc_calls: rpc reg, svc^reg, rpc_svc_calls(3N) 

svc__destroy, svc_dg_create,/ rpc_svc_create: svc_create, rpc_svc_create(3N) 

svcerr_decode, svcerrjioproc,/ rpc_svc_err: svcerr_auth, rpcjsvc_err(3N) 

svc _getargs, svc_getreqset,/ rpc_svc_reg: svc_freeargs, rpc_svc_reg(3N) 

xdr_authsys_panns, xdr_callhdry rpc_xdr: xdr_accepted_reply, rpc_xdr(3N) 

users on remote machines rusers return information about rusers(3N) 

machines rusers who's logged in on local rusers(l) 

rpcrwalld network rwall server rpc.rwalld(lM) 

network rwall write to all users over a rwall(lM) 

madiines rwall write to spedfied remote rwall(3N) 

sac service access controller sac(lM) 

administration sacadm service access controller sacadm(lM) 
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network spray scatter data in order to check the spray(3N) 

doconfig execute a configuration script doconfig(3N) 

keylogin decrypt and store secret key keylogin(l) 

getsecretkey retrieve public or secret key /getpublickey, publickey(3N) 

/user2netname library routines for secure remote procedure calls secure__rpc(3N) 

domainname get/set name of current secure RFC domain domainname(lM) 

authdes_getucred, getnetnameV secure_rpc: authdes_seccreate, secure_rpc(3N) 

select synchronous I/O multiplexing select(3C) 

t_sndudata send a data unit t_sndudata(3N) 

send, sendto, sendmsg send a message from a socket send(3N) 

connection t_snd send data or expedited data over a t_snd(3N) 

message nlsrequest format and send listener service request nlsrequest(3N) 

message from a socket send, sendto, sendmsg send a send(3N) 

request t_snddis send user-initiated disconnect t_snddis(3N) 

socket send, sendto, sendmsg send a message from a send(3N) 

a socket send, sendto, sendmsg send a message from send(3N) 

receive data or expedited data sent over a connection tjrcv tjrcv(3N) 

ypserv, ypbind YP server and binder processes ypserv(lM) 

bootparamd boot parameter server bootparamd(lM) 

ypupdated server for changing YP information ypupdated(lM) 

private keys keyserv server for storing public and ke)rserv(lM) 

for dealing with the creation of server handles /library routines rpc_svc_create(3N) 

current version of a YP map at a YP server host yppoll return yppoll(lM) 

ypwhich return name of YP server or map master ypwhich(l) 

rpcrusersd network usemame server rpc.rusersd(lM) 

rpc.rwalld network rwall server rpc.rwalld(lM) 

rpcsprayd spray server rpc.sprayd(lM) 

errors /library routines for server side remote procedure call rpc_svc_err(3N) 

ypxfr transfer YP map from a YP server to host ypxfr(lM) 

ypset p)oint ypbind at a particular server ypset(lM) 

library routines for registering servers /xprt_unregister rpc_svc_calls(3N) 

library routines for RPC servers /svc_run, svc_sendreply rpc_svc_reg(3N) 

administration sacadm service access controller sacadm(lM) 

sac service access controller sac(lM) 

setservent, endservent get service entry /getservbyname, getservent(3N) 

t_getinfo get protocol-specific service information t_getinfo(3N) 

nlsrequest format and send listener service request message nlsrequest(3N) 

library routines for RPC bind service /rpcb set, rpcb^unset rpcbind(3N) 

inetd Internet services daemon inetd(lM) 

getsockopt, setsockopt get and set options on sockets getsockopt(3N) 

host/ /gethostbyaddr, gethostbyname, sethostent endhostent get network gethostent(3N) 

entry /getnetbyaddr, getnetb)mame, setnetent, endnetent get network getnetent(3N) 

/getprotobynumber, getprotobyname, setprotoent, endprotoent get/ getprotoent(3N) 

/getservbyport, getservbyname, setservent, endservent get service/ getservent(3N) 

sockets getsockopt, setsockopt get and set options on getsockopt(3N) 

ttydefs file contains terminal line settings information for ttymon ttydefs(4) 

connection shutdown shut down part of a full-duplex shutdown(3N) 
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full-duplex connection shutdown shut down part of a shutdown (3N) 

library routines for client side calls /rpc_broadcast, rpc call rpc_dnt_calls(3N) 

/library routines for client side remote procedure call/ rpc_dnt_auth(3N) 

/library routines for server side remote procedure call errors rpc_svc_err(3N) 

accept accept a connection on a socket accept(3N) 

bind bind a name to a socket bind(3N) 

connect initiate a connection on a socket connect(3N) 

commvmication socket create an endpoint for socket(3N) 

listen listen for connections on a socket listen(3N) 

getsockname get socket name getsockname(3N) 

recvmsg receive a message from a socket recv, recvfrom, recv(3N) 

sendmsg send a message from a socket send, sendto, send(3N) 

connected sockets socketpair create a pair of socketpair(3N) 

setsockopt get and set options on sockets getsockopt, getsockopt(3N) 

create a pair of connected sockets socketpair socketpair(3N) 

ioctls that operate directly on sockets sockio sockio(7) 

on sockets sockio ioctls that operate directly sockio(7) 

rwall write to specified remote machines rwall(3N) 

spray spray packets spray(lM) 

check the network spray scatter data in order to spray(3N) 

rpcsprayd spray server rpc.sprayd(lM) 

spray spray packets spray(lM) 

dbm, dbminit, dbmclose, fetch, store, delete, firstkey, nextkey/ dbm(3) 

keylogin decrypt and store secret key keylogin(l) 

keyserv server for storing public and private keys keyserv(lM) 

for external data representation stream aeation /library routines xdr_create(3N) 

rexec return stream to a remote command rexec(3N) 

t alloc allocate a library structure t_alloc(3N) 

t_free free a library structiare tJree(3N) 

the YP database and directory structure ypfiles ypfiles(4) 

delete, firstkey, nextkey database subroutines /fetch, store, dbm(3) 

svc_dg_create,/ rpc_svc_create: svc_create, svc_destroy, rpc_svc_create(3N) 

rpc__svc_create: svc_create, svc__destroy, svc_dg_create,/ rpc_svc_create(3N) 

/svc_create, svc_destroy, svc_dg_create, svc_fd_create,/ rpc_svc_create(3N) 

svcerr_noproc,/ rpc_svc_err: svcerr_auth, svcerr_decode, rpc_svc_err(3N) 

rpc__svc_err: svcerr_auth, svcerr_decode, svcerr__noproc,/ rpc_svc_err(3N) 

/svcerr_auth, svcerr_decode, svcerr_noproc, svcerr_noprog,/ rpc_svc_err(3N) 

/svcerr_decode, svcerr_noproc, svcerr_noprog, svcerr_progvers,/ rpc_svc_err(3N) 

/svcerr_noproc, svcerr^noprog, svcerr_progvers, svcerr_systemerr,/ rpc_svc_err(3N) 

/svcerr_noprog, svcerr_j>rogvers, svcerr_systemerr, svcerr_weakauth/ , rpc_svc_err(3N) 

/svcerr_progvers, svcerr_systemerr, svcerr_weakauth library routines/ rpc_svc_err(3N) 

/svc_destroy, svc_dg_create, svc_fd_create, svc_raw_create,/ rpc_svc_create(3N) 

svc_getreqset,/ rpc__svc__reg: svc_freeargs, svc_getargs, rpc_svc_reg(3N) 

rpc_svcj:eg: svc^freeargs, svc_getargs, svc getreqset,/ rpc_svc_reg(3N) 

/ svc freeargs, svc getargs, svc getreqset, svc_getrpccaller,/ rpc_svc_reg(3N) 

/svc_getargs, svc_getreqset, svc_getrpccaller, svc_run,/ rpc_svc_reg(3N) 

/svc_dg_create, svc_fd_create, svc_raw_create, svc_tli_create,/ rpc_svc_create(3N) 
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rpc_svc_calls: rpcjreg, svc__reg, svc_unreg, xprt^register,/ rpc_svcjcalls(3N) 

/svc _^treqset svc__getrpcc^er, svc_nm, svc^sendreply library/ rpc__svc_reg(3N) 

RPC/ /svc_getrpccaller, svc_run, svc_sendreply library routines for rpc_svc_reg(3N) 

/svc_fd_create, svc^rawjreate, svc_tli_create, svc_tp_create,/ rpc_svc_create(3N) 

/svc_raw_create, svc_tli_create, svc tp create, svc vc create/ rpc_svc_create(3N) 

rpc_svc_calls: rpc^reg, svcjreg, svc unreg, xprt registerV rpc_svc_caUs(3N) 

/svc_tli_create, svc_tp_create, svc_vc_create library routines for/ rpc_svc_create(3N) 

t_sync synchronize transport library t_sync(3N) 

select synchronous I/O multiplexing select(3C) 

t_accept accept a connect request t_accept(3N) 

/netdir_free, netdir_mergeaddr, taddr2uaddr, uaddr2tad^y netdir_getbyname(3N) 

structure t alloc allocate a library t_alloc(3N) 

transport endpoint t_bind bind an address to a t_bind(3N) 

t_close dose a transport endpoint t_dose(3N) 

with another transport user t_connect establish a connection tjconnect(3N) 

Protocol TCP Internet Transmission Control TCP(7) 

dial establish an outgoing terminal line connection dial(3Q 

for ttymon ttydefs file contains terminal line settings information ttydefs(4) 

t_error produce error message t_error(3N) 

t_free free a library structure t_free(3N) 

service information t_getinfo get protocol-spedfic t_getinfo(3N) 

t_getstate get the current state t_getstate(3N) 

transport providers tidts, ticots, ticotsord loopbadc tidts(7) 

transport providers tidts, ticots, ticotsord loopbadc ticlts(7) 

providers tidts, ticots, ticotsord loopbadc transport tidts(7) 

request t listen listen for a connect t_listen(3N) 

a transport endpoint tjcx)k look at the current event on t J(x>k(3N) 

endpoint t open establish a transport t_open(3N) 

transport endpoint t optmgmt manage options for a t_optmgmt(3N) 

host ypxfr transfer YP map from a YP server to ypxfr(lM) 

generic transport name-to-address translation /netdir_sperror netdir_getbyname(3N) 

TCP Internet Transmission Control Protocol TCP(7) 

tjbind bind an address to a transport endpoint tJbind(3N) 

tjdose dose a transport endpoint t_dose(3N) 

look at the current event on a transport endpoint t_lcx)k t_look(3N) 

t open establish a transport endpoint t__open(3N) 

t_optmgmt manage options for a transport endpoint t_optmgmt(3N) 

t_unbind disable a transport endpoint t_unbind(3N) 

t_sync synchronize transport library t_sync(3N) 

translation /netdir_sperror generic transport name-to-address netdir_getbyname(3N) 

nlsprovider get name of transport provider nlsprovider(3N) 

tidts, ticots, ticotsord loopbadc transport providers tidts(7) 

establish a connection with another transport user t connect t_connect(3N) 

data[ sent over a connection t rcv receive data or expedited t_rcv(3N) 

confirmation from a connect/ t rcvconnect receive the t_rcvconnect(3N) 

disconnect t__rcvdis retrieve information from t_rcvdis(3N) 

orderly release indication t_rcvrel acknowledge receipt of an tj:cvrel(3N) 
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t_rcvudata receive a data unit t_rcvudata(3N) 

error indication t rcvuderr receive a unit data t_rcvuderr(3N) 

over a connection t_snd send data or expedited data t_snd(3N) 

disconnect request t snddis send user-initiated t_snddis(3N) 

release t_sndrel initiate an orderly t_sndrel(3N) 

t_sndudata send a data unit t_sndudata(3N) 

library t_sync synchronize transport t_sync(3N) 

settings information for ttjrmon ttydef s file contains terminal line ttydef s(4) 

line settings information for ttymon /file contains terminal ttydefs(4) 

endpoint t_imbind disable a transport tjmbind(3N) 

/netdirjnergeaddr, taddr2uaddr, uaddr2taddr, netdir j>error,/ netdir_getbyname(3N) 

UDP Internet User Datagram Protocol UDP(7) 

t_rcvuderr receive a tmit data error indication t j:cvuderr(3N) 

t_rcvudata receive a data unit t_rcvudata(3N) 

t_sndudata send a data unit t_sndudata(3N) 

niimber mapper rpcbind universal addresses to RPC program rpcbind(lM) 

updating updaters configuration file for YP updaters(4) 

updaters configuration file for YP updating updaters(4) 

UDP Internet User Datagram Protocol UDP(7) 

chkey change user encryption key chkey(l) 

environ user environment environ(5) 

a connection with another transport user t_connect establish t_connect(3N) 

secure/ /netname2host, netname2user, user2netname library routines for secure_rpc(3N) 

t snddis send user-initiated disconnect request t_snddis(3N) 

rpcrusersd network usemame server rpcrusersd(lM) 

rusers return information about users on remote machines rusers(3N) 

rwall write to all users over a network , rwall(lM) 

map ypmatch print the value of one or more keys from a YP ypmatch(l) 

/htonl, htons, ntohl, ntohs convert values between host and network/ byteorder(3N) 

)rpcat print values in a YP data base ypcat(l) 

host yppoll return current version of a YP map at a YP server yppoll(lM) 

nlsgetcall get client's data passed via the listener nlsgetcall(3N) 

rusers who's logged in on local machines rusers(l) 

rwall write to all users over a network rwall(lM) 

rwall write to specified remote machines rwall(3N) 

data representation xdr library routines for external xdr(3N) 

/xdr_rejected_reply, xdr replymsg XDR library routines for remote/ rpc_xdr(3N) 

xdr_authsys__parms,/ rpc xdr: xdr_accepted_reply, rpc_xdr(3N) 

xdrrec_eof, xdr_setpos library/ xdr^admin: xdr_getpos, xdr Jnline, xdr_admin(3N) 

xdr_pointer,/ xdr complex: xdr array, xdr bytes, xdr opaque, xdr_complex(3N) 

rpc_xdr: xdr_accepted_reply, xdr_authsys_parms, xdr callhdr,/ rpc_xdr(3N) 

xdr^enum, xdr_float,/ xdr_simple: xdr bool, xdr char, xdr double, xdr_simple(3N) 

xdr_complex: xdr_array, xdr bytes, xdr opaque, xdr_pointer,/ xdr_complex(3N) 

/xdr_authsys_parms, xdr_callhdr, xdr^callmsg,/ rpc_xdr(3N) 

/xdr_authsys__parms, xdr_callhdr, xdr callmsg, xdrjopaque auth,/ rpc_xdr(3N) 

xdrjloat,/ xdr simple: xdr_bool, xdr char, xdr^double, xdr eniam, xdr_simple(3N) 

xdr_opaque, xdr_pointer,/ xdr_complex: xdr_array, xdr_bytes, xdr_complex(3N) 
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xdrmem_create, xdrrec_create,/ xdr_create: xdr_destroy, xdr_create(3N) 

xdrrecjreate,/ xdr_create; xdr_destroy, xdrmemjreate, xdr_create(3N) 

xdr simple: xdr_bool, xdr_char, xdr double, xdr eniim, xdrjloat,/ xdr_simple(3N) 

/xdr bool, xdr char, xdr double, xdr enum, xdr float, xdr free,/ xdr_simple(3N) 

/xdr^char, xdr double, xdr enum, xdr float, xdr^free, xdr jni,/ xdr_simple(3N) 

/xdr_double, xdr enum, xdr_float, xdr_free, xdrjnt, xdrjong,/ xdr_simple(3N) 

xdr^setpos library/ xdr^admin: xdr_getpos, xdr_inline, xdrrec_eof, xdr_admin(3N) 

library/ xdr_admin: xdr^etpos, xdr_inline, xdrrec_eof, xdr__setpos xdr_adimn(3N) 

/xdr^enmn, xdr_float, xdr_free, xdr^int, xdrjong, xdr^short,/ xdr__simple(3N) 

/xdr Jloat, xdr^free, xdr_int, xdr jong, xdr__short, xdr_u_char,/ xdr_simple(3N) 

xdr_create: xdr_destroy, xdrmem_create, xdrrec^aeate,/ xdr_create(3N) 

xdr_complex: xdr array, xdr bytes, xdr_opaque, xdr_pointer,/ xdr_complex(3N) 

/xdr_callhdr, xdr_callmsg, xdr_opaque_auth,/ rpc_xdr(3N) 

/xdr array, xdr bytes, xdr opaque, xdr_j>ointer, xdr reference,/ xdr_complex(3N) 

/xdr destroy, xdrmem create, xdrrec create, xdrstdio create/ xdr_create(3N) 

xdr admin: xdr_^etpos, xdr inline, xdrrec_eof, xdr setpos library/ xdr_adnun(3N) 

/xdr_bytes, xdr_opaque, xdrjpointer, xdr_reference, xdr_string,/ xdr_complex(3N) 

XDR/ /xdr_callmsg, xdr_opaque_auth, xdr_rejected_reply, xdrj-eplymsg rpc_xdr(3N) 

for remote/ /xdr_rejected_reply, xdr_repl)ansg XDR library routines rpc_xdr(3N) 

/xdr_getpos, xdr^inline, xdrrec_eof, xdr_setpos library routines for/ xdr_admin(3N) 

/xdr_free, xdrjnt, xdrjong, xdr_short, xdr_u_char, xdr_uJong,/ xdr_simple(3N) 

xdr_double, xdr_enum, xdr_float,/ xdr_simple: xdr^bool, xdr_char, xdr_simple(3N) 

for/ /xdrmem_create, xdrrec_create, xdrstdio_create library routines xdr_create(3N) 

/xdr_pointer, xdr_reference, xdr^string, xdr_union, xdr_vector,/ xdr_complex(3N) 

xdr_int, xdrjong, xdr__short, xdr_u_char, xdr_uJong,/ /xdr Jree, xdr_simple(3N) 

/xdrjong, xdr_short, xdr_u_char, xdr_uJong, xdr_u_short, xdr_void/ xdr_simple(3N) 

/xdr reference, xdr string, xdr union, xdr vector,/ xdr_complex(3N) 

/xdr_short, xdr_u_char, xdr_uJong, xdr_u_short, xdr_void library/ xdr_simple(3N) 

routines/ /xdr string, xdr imion, xdr_yector, xdr wrapstring library xdr_complex(3N) 

external/ /xdr u long, xdr u short, xdr^void library routines for xdr_simple(3N) 

/xdr_string, xdr jmion, xdr vector, xdr_wrapstring library routines for/ xdr_complex(3N) 

/rpc^reg, svc^reg, svcjmreg, xprt register, xprt vmregister/ rpc_svc_calls(3N) 

/svc_reg, svc^tinreg, xprt register, xprt imregister library routines/ rpc_svc_calls(3N) 

yp_master, yperr string, ypprot err YP client interface /yp_order, ypdnt(3N) 

5^at print values in a YP data base ypcat(l) 

ypfiles the YP database and directory structure ypfQes(4) 

ypinit build and install YP database ypinit(lM) 

ypmake rebuild YP database ypmake(lM) 

makedbm make a YP dbm file makedbm(lM) 

yp^update changes yp information yp_update(3N) 

ypupdated server for changing YP information ypupdated(lM) 

yppoU return current version of a YP map at a YP server host yppoll(lM) 

ypxfr transfer YP map from a YP server to host ypxfr(lM) 

value of one or more keys from a YP map ypmatch print the ypmatch(l) 

force propagation of a changed YP map yppush yppush(lM) 

ypserv, )rpbind YP server and binder processes ypserv(lM) 

current version of a YP map at a YP server host yppoU return yppoll(lM) 
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ypwhich return name of YP server or map master ypwhich(l) 

ypxfr transfer YP map from a YP server to host ypxfr(lM) 

updaters configuration file for YP updating updaters(4) 

/yp_match, yp_first, yp_next, yp_all/ yp_order, yp master,/ ypclnt(3N) 

ypset point ypbind at a particular server ypset(lM) 

processes ypserv, ypbind YP server and binder ypserv(lM) 

ypdnt yp _^et_default_domain, ypjbind, yp_unbind, yp^match^ ypdnt(3N) 

base ypcat print values in a YP data ypcat(l) 

yp^bind, yp^unbind, yp match,/ ypclnt, yp^et^defaultjdomain, ypclnt(3N) 

/yp_all, yp_order^ )rp_master, yperr_string, ypprot_err YP dient/ ypclnt(3N) 

directory structure ypfiles the YP database and ypfiles(4) 

/yp bind, yp unbind, yp^match, yp_first yp__next yp_all,/ ypdnt(3N) 

yp^imbind, yp_match,/ ypdnt, yp__get_default_domain, yp_bind, )^xJnt(3N) 

database ypinit build and install YP ypinit(lM) 

ypmake rebuild YP database ypmake(lM) 

YP/ /yp next, yp__all, yp order, ypjnaster, yperr_string, ypprot_err ypclnt(3N) 

more keys from a YP map ypmatch print the value of one or ypmatch(l) 

YPjSl,/ /yp__bind, yp__imbind, ypjnatch, yp_first, yp^next, ypclnt(3N) 

/ypjmbind, yp_match, yp^first, ypjiext, yp__all, yp_order,/ ypclnt(3N) 

/yp_first, yp_next, yp_all, yp^order, yp_master, yperr^string,/ ypclnt(3N) 

YP map at a YP server host yppoU return current version of a yppoll(lM) 

/yP-Order, yp^master, yperr_string, ypprot^err YP client interface ypchit(3N) 

changed YP map yppush force propagation of a yppush(lM) 

processes ypserv, ypbind YP server and binder ypserv(lM) 

server ypset point ypbind at a particular ypset(lM) 

/yP-.g®L^6^^^L^o°^^/ yp^bind, ypjmbind, yp_match, ypjirst,/ ypclnt(3N) 

yp jipdate dianges yp information yp_update(3N) 

information ypupdated server for changing YP ypupdated(lM) 

map master ypwhich return name of YP server or ypwhich(l) 

server to host ypxfr transfer YP map from a YP ypxfr(lM) 
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NAME 

chkey - change user encryption key 

SYNOPSIS 

chkey 

DESCRIPTION 

The chkey command prompts for a password and uses it to encrypt a new user 
encryption key. The encrypted key is stored in the publickey(4) database. 

This command should be executed only on the master server for the 
publickey(4) database. 

SEE ALSO 

keylogin(l), keylogout(l), publickey(4X keyservdM), newkey(l). 
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NAME 

key login - decrypt and store secret key 

SYNOPSIS 

keylogin 

DESCRIPTION 

The keylogin command prompts for a password, and uses it to decrypt the 
user's secret key stored in the publickey(4) database. Once decrypted, the user's 
key is stored by the local key server process, keyserv(lM), to be used by any 
secure network service, such as NFS. 

SEE ALSO 

chkey(l), keylogout(l) , publickey(4), keyserv(lM), newkeyd). 
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NAME 

rpcgen - an RFC protocol compiler 

SYNOPSIS 

rpcgen infile 

rpcgen {-Dnamel^alue]] [-T] [-Yi sees] infile 

rpcgen -c|-h(-l|-in|-t [-o ouifile ] infile 

rpcgen -s nettype [-o outfile] infile 

rpcgen -n nettd [-o outfik] infile 

DESCRIPTION 

rpcgen is a tool that generates C code to implement an RFC protocol. The input 
to rpcgen is a language similar to C known as RFC Language (Remote Procedure 
Call Language). 

rpcgen is normally used as in the first synopsis where it takes an input file and 
generates up to four output files. If the infile is named proto.:^ then rpcgen will 
generate a header file in proto.h, XDR routines in proto_xdr.c, server-side 
stubs in proto_svc.c, and client-side stubs in proto__clnt . c. With the -T 
option, it will also generate the RFC dispatch table in proto_tbl . i. 

The server created can be started both by the port monitors (for example, inetd 
or listen) or by itself. When it is started by a port monitor, it creates servers 
only for the transport for which the file descriptor 0 was passed. The name of 
the transport must be specified by setting up the environmental variable 
PMJTRANSPORT. When the server generated by rpcgen is executed, it creates 
server handles for all the transports specified in NETPATH environment variable, 
or if it is unset, it creates server handles for all the visible transports from 
/etc/netconf ig file. Note: the transports are chosen at run time and not at 
compile time. When the server is self-started, it backgrounds itself by default. A 
special define symbol RPCJSVC__FG can be used to run the server process in fore- 
ground. 

The second synopsis provides special features which allow for the creation of 
more sophisticated RFC servers. These features include support for user pro- 
vided #def ines and RFC dispatch tables. The entries in the RFC dispatch table 
contain: 

• pointers to the service routine corresponding to that procedure, 

• a pointer to the input and output arguments 

• the size of these routines 

A server can use the dispatch table to check authorization and then to execute the 
service routine; a client library may use it to deal with the details of storage 
management and XDR data conversion. 

The other three synopses shown above are used when one does not want to gen- 
erate all the output files, but only a particular one. Some examples of their usage 
is described in the EXAMFLE section below. When rpcgen is executed with the 
-s option, it creates servers for that particular class of transports. When executed 
with the -n option, it creates a server for the transport specified by netid. If infile 
is not specified, rpcgen accepts the standard input. 
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The C preprocessor, cc -E [see cc(l)], is run on the input file before it is actually 
interpreted by rpcgen. For each type of output file, rpcgen defines a special 
preprocessor symbol for use by the rpcgen programmer: 

RPCJiDR defined when compiling into header files 

RPC_XDR defined when compiling into XDR routines 

RPCJSVC defined when compiling into server-side stubs 

RPCJCLNT defined when compiling into client-side stubs 

RPCJTBL defined when compiling into RFC dispatch tables 

Any line beginning with is passed directly into the output file, uninterpreted 
by rpcgen. 

For every data type referred to in infile, rpcgen assumes that there exists a rou- 
tine with the string xdr_ prepended to the name of the data type. If this routine 
does not exist in the RPC/XDR library, it must be provided. Providing an 
undefined data type allows customization of XDR routines. 

The following options are available: 

-c Compile into XDR routines. 

-Dname [rvalue] 

Define a symbol name. Equivalent to the #def ine directive in the source. 
If no value is given, value is defined as 1. This option may be specified 
more than once. 

-h Compile into C data-definitions (a header file). -T option can be used in 
conjunction to produce a header file which supports RFC dispatch tables. 

-Ksecs 

By default, services created using rpcgen wait 120 seconds after servicing 
a request before exiting. That interval can be changed using the -K flag. 
To create a server that exits immediately upon servicing a request, -K 0 
can be used. To create a server that never exits, the appropriate argument 
is -K -1. 

When monitoring for a server, some portmonitors, like listen(lM), 
always spawn a new process in response to a service request. If it is 
known that a server will be used with such a monitor, the server should 
exit immediately on completion. For such servers, rpcgen should be used 
with -K -1. 

-1 Compile into client-side stubs. 

-m Compile into server-side stubs, but do not generate a main routine. This 
option is useful for doing callback-routines and for users who need to 
write their own main routine to do initialization. 

-n netid 

Compile into server-side stubs for the transport specified by netid. There 
should be an entry for netid in the netconfig database. This option may be 
specified more than once, so as to compile a server that serves multiple 
transports. 
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-o outfile 

Specify the name of the output file. If none is specified, standard output 
is used (-C, -h, -1, -nv -n, -s and -t ntodes only). 

-s nettype 

Compile into server-side stubs for all the transports belonging to the class 
nettype. The supported classes are netpath, visible, circuitj:i, 
circuit_v, datagramjn, datagram_v, tcp, and udf> [see rpc(3ND for the 
meanings associated with these classes]. This option may be specified 
more than once. Note: the transports are chosen at run time and not at 
compile time. 

-t Compile into RPC dispatch table. 

-T Generate the code to support RPC dispatch tables. 

The options -c, -h, -1, -nv -s and ~t are used exclusively to generate a particu- 
lar type of file, while the options -D and -T are global and can be used with the 
other options. 

NOTES 

The RPC Language does not support nesting of structures. As a work-around, 
structures can be declared at the top-level, and their name used inside other 
structures in order to achieve the same effect. 

Name clashes can occur when using program definitions, since the apparent scop- 
ing does not really apply. Most of these can be avoided by giving unique names 
for programs, versions, procedures and types. 

The server code generated with -n option refers to the transport indicated by 
netid and hence is very site specific. 

EXAMPLE 

The following example: 

$ rpcgen -T prot.x 

generates all the five files: prot.h, prot_clnt.c, prot_svc.c, prot_xdr.c and 
prot Jtbl . i. 

The following example sends the C data-definitions (header file) to the standard 
output. 

$ rpcgen -h prot.x 

To send the test version of the -DTEST, server side stubs for all the transport 
belonging to the class datagramjn to standard output, use: 

$ rpcgen -s datagraxn_n -DTEST prot.x 

To create the server side stubs for the transport indicated by netid tcp, use: 

$ rpcgen -n tcp prot_svc.c prot.x 

SEE ALSO 

cc(l). 
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NAME 

rusers - who's logged in on local machines 

SYNOPSIS 

rusers [ -ahilu ] host . . . 

DESCRIPTION 

The rusers command produces output similar to who(l), but for remote 
machines. The listing is in the order that responses are received, but this order 
can be changed by specifying one of the options listed below. 

The default is to print out the names of the users logged in. When the -1 flag is 
given, additional information is printed for each user, including idle time, when 
user logged in, and tty. 

A remote host will only respond if it is running the rusersddM) daemon, which 
may be started up from inetd(lM) or listen(lM). 

The following options are available: 

-a Give a report for a machine even if no users are logged on. 
-h Sort alphabetically by host name, 
-i Sort by idle time. 

-1 Give a longer listing in the style of who(l). 
~u Sort by number of users. 
SEE ALSO 

inetddM), listen(lM), pitadni(lM), rusersddM), sacadmdM), who(l). 
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NAME 

ypcat ~ print values in a YP data base 

SYNOPSIS 

ypcat [ -k ] [ -d ypdomain ] mname 

DESCRIPTION 

The ypcat command prints out values in the YP name service map specified by 
mname, which may be either a map name or a map nickname. Since ypcat uses 
the YP network services, no YP server is specified. 

Refer to yp£ile8(4) and ypserv(lM) for an overview of the YP name service. 

The following options are available: 

-d ypdomain 

Specify a domain other that the default domain. 

-k Display the keys for those maps in which the values are null or the key is 
not part of the value. None of the maps derived from files that have an 
ASCI version in /etc fall into this class. 

SEE ALSO 

ypmatchd), ypserv(lM), ypf iles(4) 
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NAME 

5^match - print the value of one or more keys from a YP map 
SYNOPSIS 

ypmatch [ -d ypdomain ] [ -k ] key. . . tnname 
DESCRIPTION 

ypmatch prints the values associated with one or more keys from the YPs name 
services map specified by mname, which may be either a mapname or an map nick- 
name. 

Multiple keys can be specified; the same map will be searched for all keys. The 
keys must be exact values insofar as capitalization and length are concerned. No 
pattern matching is available. If a key is not matched, a diagnostic message is 
produced. 

The following options are available: 
-d ypdomain 

Specify a domain other than the default domain. 

-k Before printing the value of a key, print the key itself, followed by a 

colon . This is useful only if the keys are not duplicated in the values, or 
so many keys were specified that the output could be confusing. 

SEE ALSO 

ypcat(l), ypf iles(4) 
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NAME 

ypwhich - return name of YP server or map master 

SYNOPSIS 

ypwhich [ -d [ ypdormin ] 1 [ hostname ] 
ypwhich [ -d ypdomain ] -m [ mmme ] 

DESCRIPTION 

ypwhich tells which YP server supplies the YP name services to a YP client, or 
which is the master for a map. If invoked without arguments, it gives the YP 
server for the local machine. If hostname is specified, that machine is queried to 
find out which YP master it is using. 

Refer to ypf iles(4) and ypserv(lM) for an overview of the YP name services. 

The following options are available: 

-d [ypdomain] 

Use ypdomain instead of the default domain. 

-^mname 

Find the master YP server for a map. No hostname can be specified with 
-m. mname can be a mapname, or a nickname for a map. When mname is 
omitted, produce a list available maps. 

SEE ALSO 

ypserv(lM), ypset(lM), ypf iles(4) 
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NAME 

bootparamd - boot parameter server 

SYNOPSIS 

bootparamd [ -d ] 

DESCRIPTION 

bootparamd is a server process that provides information to diskless clients 
necessary for booting. It obtains its information from the /etc/bootparams file. 

bootparamd can be invoked either by inetd(lM) or by the user. 

The -d option displays the debugging information. 

FILES 

/etc/bootparams 

SEE ALSO 

inetd(lM) 



10/89 



Page 1 



domalnname(IM) 



domainname(IM) 



NAME 

domainname - get/set name of current secure RFC domain 

SYNOPSIS 

domainname [ newmme ] 

DESCRIPTION 

The domainname command is used on secure RFC machines. With no argument, 
the name of the machine's secure RFC domain is written to standard output. 

root privileges are required to use the domainname command with an argument. 
In this form, the command sets the name of the secure RFC domain to newmme. 
newmme may be up to 255 characters long. 

domainname is normally run by the network administrator on all machines using 
secure RFC to set the name of the secure RFC domain. To use secure RFC, 
machines must have a secure RFC domain name. 

NOTES 

Secure RFC domain names are not related to ans should not be confused with 
RFS domains. 

The RFC package expects the newmme argument to be a valid filename for the 
underlying file system in use on the networked machines using secure RFC. For 
example, machines based on the s5 file system should not have domain names 
longer than 14 characters in length or problems may occur when using secure 
RFC. 

The secure RFC domain name set by domainname will not be remembered across 
reboots. To give a machine a "permanent" name, set the SRPCJX)MAIN tunable in 
/etc/master. d/kemel to the secure RFC domain name. 

SEE ALSO 

RPC Administration in the Programmer's Guide: Networking Interfaces. 
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NAME 

inetd - Internet services daemon 

SYNOPSIS 

inetd [ -d ] [ -s ] [ configuration-file ] 



Inetd (1M) 



DESCRIPTION 

inetdy the Internet services daemon, is normally run at boot time by the Service 
Access Facility (SAF). When started, inetd reads its configuration information 
from configuration-file, the default being /etc/ inetd . conf. See inetd.conf(4) 
for more information on the format of this file. It listens for connections on the 
Internet addresses of the services that its configuration file specifies. When a con- 
nection is found, it invokes the server daemon specified by that configuration file 
for the service requested. Once a server process exits, inetd continues to listen on 
the socket. 

The -s option allows you to nm inetd "stand-alone/' outside the Service Access 
Facility (SAF). 

Rather than having several daemon processes with sparsely distributed requests 
each running concurrently, inetd reduces the load on the system by invoking 
Internet servers only as they are needed. 

inetd itself provides a number of simple TCP-based services. These include 
echo, discard, chargen (character generator), daytixne (human readable time), 
and time (machine readable time, in the form of the number of seconds since 
midnight, January 1, 1900). For details of these services, consult the appropriate 
RFC, as listed below, from the Network Information Center. 

inetd rereads its configuration file whenever it receives a hangup signal, SIGHUP. 
New services can be activated, and existing services deleted or modified in 
between whenever the file is reread. 

SEE ALSO 

comsatdM), ftpd(lM), rexecddM), rlogind(lM), rshddM), telnetd(lM), 
tftpddM), inetd. conf (4). 

Postel, Jon, "Echo Protocol/' RFC 862, Network Information Center, SRI Inter- 
national, Menlo Park, Calif., May 1983. 

Postel, Jon, "Discard Protocol/' RFC 863, Network Information Center, SRI 
International, Menlo Park, Calif., May 1983. 

Postel, Jon, "Character Generater Protocol," RFC 864, Network Information 
Center, 

SRI International, Menlo Park, Calif., May 1983. 

Postel, Jon, "Daytime Protocol/' RFC 867, Network Information Center, SRI Inter- 
national, Menlo Park, Calif., May 1983. 

Postel, Jon, and Ken Harrenstien, 'Time Protocol," RFC 868, Network Informa- 
tion Center, SRI International, Menlo Park, Calif., May 1983. 
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NAME 

keyserv - server for storing public and private keys 

SYNOPSIS 

keyserv [-n] 

DESCRIPTION 

keyserv is a daenion that is used for storing the private enayption keys of each 
user logged into the system. These encryption keys are used for accessing secure 
network services such as secure NFS. 

Normally, root's key is read from the file /etc/ . rootkey when the daemon is 
started. This is useful during power-fail reboots when no one is around to type a 
password. 

When the -n option is used, root's key is not read from /etc/ . rcx>tkey. Instead, 
keyserv prompts the user for the password to decrypt root's key stored in the 
publickey(4) database and then stores the decrypted key in /etc/ .rootkey for 
future use. This option is useful if the /etc/ . rootkey file ever gets out of date 
or corrupted. 

FILES 

/etc/ . rootkey 

SEE ALSO 

publickey(4). 
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NAME 

makedbm - make a YP dbm file 
SYNOPSIS 

/usr/sbin/makedbm [-1] [-s] [-i ypjnputjik] [-o ypj)utput_naine] 
[-d ypjioiminjtame] [-m ypjnasterjiame] infile outfile 

makedbm [-u dbmfilemme] 

DESCRIPTION 

The makedbm command takes infile and converts it to a pair of files in dbro(3) for- 
mat, namely out file, pag and outfile, dir. Each line of the input file is converted to 
a single dlxn record. All characters up to the first TAB or SPACE form the key, and 
the rest of the line is the data. If a line ends with '\'/ then the data for that 
record is continued on to the next line. It is left for the clients of the YP name 
service to interpret '#'; makedbm does not itself treat it as a comment character. 
infile can be in which case the standard input is read. 

makedbm is meant to be used in generating dbm files for the YP name service, and 
it generates a special entry with the key ypjastjnodified, which is the date of infile 
(or the current time, if infile is '-'). 

The following options are available: 

-1 Lowercase. Convert the keys of the given map to lower case, so that host 
name matches, for example, can work independent of upper or lower case 
distinctions. 

-s Secure map. Accept connections from secure YP networks only. 

~i ypjnputjile 

Create a special entry with the key ypjnputjile. 

-o ypj)utputjiame 

Create a special entry with the key ypjmtputjtame. 

-d ypjbmainjtame 

Create a special entry with the key ypjbmainjiame, 

-m ypjnasterjiame 

Create a special entry with the key ypjnasterjiame. If no master host 
name is specified, ypjnasterjiame will be set to the local host name. 

-u dhmfilename 

Undo a dbm file. That is, print out a dbm file one entry per line, with a 
single space separating keys from values. 

SEE ALSO 

dbm(3) 



10/89 



Page 1 



newkey(1M) 



ndwkey(IM) 



NAME 

newkey - create a new key in the publickey database 

SYNOPSIS 

newkey -h hostname 

newkey -u usemame 
DESCRIPTION 

The newkey cx>mmand is normally run by the network administrator on the 
machine that contains the piiblickey(4) database, to establish public keys for 
users and privileged users on the network. These keys are needed when using 
secure RFC or secure NFS. 

newkey will prompt for a password for the given usemame or hostname and then 
create a new public/ secret key pair for the user or host in /etc/publickey, 
encrypted with the given password. 

The following options are available: 

-h hostname Create a new public/secret key pair for the privileged user at the 
given hostname. Prompts for a password for the given hostname, 

-u username Create a new public/secret key pair for the given usemame. 
Prompts for a password for the given usemame, 

SEE ALSO 

chkeydX keylogin(l), keylogout(l), keyserv(lM), publickey(4) 
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NAME 

pmadm - port monitor administration 
SYNOPSIS 

pmadm -a [ippmtag \ -ttype] -asvctag-i id -^pmspecific 
-V ver [-f xu] [-y comment] [-z script] 

pmadm -r ~p pmtag -s svdag 

pmadm -e -p pmtag -s svdag 

pmadm -d -p pmtag -s svdag 

pmadm -1 [-t t}/pe \ -p pmtag] [-s svdag] 

pmadm -L [-t type | -p pmtag] [-s st?dag] 

pmadm -g -p pmtag -s svdag [-z scrxpt] 

pmadm -g -s svdag -t type -z script 

DESCRIPTION 

pmadm is the administrative command for the lower level of the Service Access 
Facility hierarchy, that is, for service administration. A port may have only one 
service associated with it although the same service may be available through 
more than one port. In order to uniquely identify an instance of a service the 
pmadm command must identify both the port monitor or port monitors through 
which the service is available (-p or -t) and the service (-s). See the option 
descriptions below. 

pmadm performs the following fimctions: 

- add or remove a service 

- enable or disable a service 

- install or replace a per-service configuration script 

- print requested service information 

Any user on the system may invoke pmadm to request service status (-1 or -L) or 
to print per-service configuration scripts (-g without the -z option), pmadm with 
other options may be executed only by a privileged user. 

The options have the following meanings: 

-a Add a service, pmadm adds an entry for the new service to the port 
monitor's administrative file. Because of the complexity of the options 
and arguments that follow the -a option, it may be convenient to use a 
command script or the menu system to add services. If you use the 
menu system, enter sysadm ports, then choose the portjservices 
option. 

-d Disable a service. Add x to the flag field in the entry for the service 
svdag in the port monitor's administrative file. This is the entry used by 
port monitor pmtag. See the -f option, below, for a description of the 
fiags available. 
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-e Enable a service. Remove x from the flag field in the entry for the ser- 
vice svctag in the port monitor administrative file. This is the entry used 
by port monitor pmtag. See the -f option, below, for a description of the 
flags available. 

-f xu The -f option specifies one or both of the following two flags which are 
then included in the flag field of the entry for the new service in the port 
monitor's administrative file. If the -f option is not included, no flags 
are set and the default conditions prevail. By default, a new service is 
enabled and no utinp entry is created for it. A -f option without a fol- 
lowing argument is illegal. 

X Do not enable the service svctag available through 
port monitor pmtag. 

u Create a utirp entry for service svctag available through 
port monitor pmtag. 

-g Print, install, or replace a per-service configuration script. The -g option 
with a -p option and a -s option prints the per-service configuration 
script for service svctag available through port monitor pmtag. The -g 
option with a -p option, a -s option, and a -z option installs the per- 
service configuration script contained in the file script as the per-service 
configuration script for service svctag available through port monitor 
pmtag. The -g option with a -s option, a -t option, and a -z option 
installs the file script as the per-service configuration script for service 
svctag available through any port monitor of type type. Other combina- 
tions of options with -g are invalid. 

~i id id is the identity that is to be assigned to service svctag when it is 
started, id must be an entry in /etc/passwd. 

-1 The -1 option requests service information. Used by itself and with the 
options described below it provides a filter for extracting information in 
several different groupings. 

-1 By itself, the -1 option lists all services on the system. 

-1 -p pmtag Lists all services available through port monitor pmtag. 

-1 -s svctag Lists all services with tag svctag. 

-1 -p pmtag -3 svctag 

Lists service svctag. 

-1 -t type Lists all services available through port monitors of type 
type. 

-1 -t type -s svctag 

Lists all services with tag svctag available through a port 
monitor of type type. 

Other combinations of options with -1 are invalid. 
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-L The -L option is identical to the -1 option except that output is printed 
in a condensed fonnat. 

-m ptnspecific 

pmspecific is the port monitor-specific portion of the port monitor admin- 
istrative file entry for the service. 

-p pmtag 

Specifies the tag associated with the port monitor through which a ser- 
vice (specified as ~s svctag) is available. 

-r Remove a service. When pmadm removes a service, the entry for the ser- 
vice is removed from the port monitor's administrative file. 

-s svctag 

Specifies the service tag associated with a given service. The service tag 
is assigned by the system administrator and is part of the entry for the 
service in the port monitor's administrative file. 

-t type Specifies the the port monitor type. 

-V ver Specifies the version number of the port monitor administrative file. The 
version number may be given as 

-V ^pmspec -V^ 

where ptnspec is the special administrative command for port monitor 
pmtag. This special command is ttyadm for ttymon and nlsadmin for 
listen. The version stamp of the port monitor is known by the com- 
mand and is returned when pmspec is invoked with a -V option. 

-y comment 

Associate comment with the service entry in the port monitor administra- 
tive file. 

-z script 

Used with the -g option to specify the name of the file that contains the 
per-service configuration script. Modifying a configuration script is a 
three-step procedure. First a copy of the existing script is made (-g 
alone). Then the copy is edited. Finally, the copy is put in place over 
the existing script (-g with -z). 

OUTPUT 

If successful, pmadm will exit with a status of 0. If it fails for any reason, it will 
exit with a nonzero status. 

Options that request information write the requested information to the standard 
output. A request for information using the -1 option prints column headers and 
aligns the information under the appropriate headings. In this format, a missing 
field is indicated by a hyphen. A request for information in the condensed for- 
mat using the -L option prints the information in colon-separated fields; missing 
fields are indicated by two successive colons. # is the comment character. 

EXAMPLES 

Add a service to a port monitor with tag pmtag. Give the service the tag svctag. 
Port monitor-specific information is generated by specpm. The service defined by 
svctag will be invoked with identity root. 
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pmadm -a -p pmtag -s svctag -i root -m ^specpm -a argl -b ar92^ \ 
-V ^specpm -V" 

Add a service with service tag svctag, identity guest, and port monitor-specific 
information generated by spe<^ to all port monitors of type type: 

pmadm -a -s svctag -i guest -t type -m ^specpm -a argl -b arg2^ \ 
-V ^specpm -V^ 

Remove the service svctag from port monitor pmtag: 

pmadm -r -p pmtag -s svctag 
Enable the service svctag available through port monitor pmtag: 

pmadm -e -p pmtag -s svctag 
Disable the service svctag available through port monitor pmtag: 

pmadm -d -p pmtag -s svctag 
List status information for all services: 

pmadm —1 

List status information for all services available through the port monitor with tag 
ports: 

pmadm -1 -p ports 

List the same information in condensed format: 

pmadm — L -p ports 

List status information for all services available through port monitors of type 
listen: 

pmadm -1 -t listen 

Print the per-service configuration script associated with the service svct:ag avail- 
able through port monitor pmtag: 

pmadm -g -p pmtag -s svctag 

FILES 

/ etc/ aaf /pmtag/ j2onfig 
/ etc/ aaf /pmtag/ svctag 
/var/aaf /pmtag/* 

SEE ALSO 

doconfigOnX sacadmdM), sac(lM). 
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NAME 

rpcbind - universal addresses to RFC program number mapper 

SYNOPSIS 

rpcbind 

DESCRIPTION 

rpcbind is a server that converts RFC program numbers into universal addresses. 
It must be running to make RFC calls. 

When an RFC service is started, it will tell rpcbind at what address it is listen- 
ing, and what RFC program numbers it is prepared to serve. When a client 
wishes to make an RFC call to a given program number, it will first contact 
rpcbind on the server machine to determine the address where RFC packets 
should be sent. 

Normally, standard RFC servers are started by port monitors, so rpcbind must 
be started before port monitors are invoked. 

rpcbind is restricted to users with appropriate privileges. 

NOTES 

If rpcbind crashes, all RFC servers must be restarted. 

SEE ALSO 

rpcinfo(lM). 
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NAME 

rpcinf o - report RPC information 

SYNOPSIS 

rpcinfo [host] 
rpcinfo -p Ihost] 

rpcinfo -T transport host program version 
ZTpcinf o [-n portnum] -u host program version 
rpcinfo [-n portnum] -t host program version 
rpcinfo -a servjddress -T transport program [version] 
rpcinfo -b [-T transport] program version 
rpcinfo -d [-T transport] program version 

DESCRIPTION 

rpcinfo makes an RPC call to an RPC server and reports what it finds. 

In the first synopsis, it lists all the registered RPC services with rpcbind on host. 
If host is not specified, it defaults to the local host. 

In the second synopsis, it lists all the RPC services registered with portmapper. 
Also note that the format of the information is different in the first and the 
second synopsis; this is because in the first case, rpcbind (version 3) is contacted, 
while in the second case portunap (version 2) is contacted for information. 

The third s5mopsis makes an RPC call to procedure 0 of program and version on 
the specified host and reports whether a response was received, transport is the 
transport which has to be used for contacting the given service. The remote 
address of the service is obtained by making a call to remote rpcbind. 

The other ways of using rpcinfo are described below. See EXAMPLES. 

The following options are available: 

-T transport Specify the transport on which the service is required. If this 
option is not specified, rpcinfo uses the transport specified in 
the NETPATH environment variable, or if that is unset or null, in 
the netconfig database. This is a generic option, and can be used 
in conjunction with any other option, except the -b option. 

-a servjiddress Use serv_address as the (universal) address for the service on tran- 
sport, to ping procedure 0 of the specified program and report 
whether a response was received. The use of -T option is 
required with -a option. 

If version number is not specified, rpcinfo tries to ping all the 
available version numbers for that program nimiber. This option 
avoids calls to remote rpcbind to find the address of the service. 
The servjiddress is specified in universal address format of the 
given transport. 

-b Make an RPC broadcast to procedure 0 of the specified program 

and version and report all hosts that respond. If transport is 
specified, it broadcasts its request only on the transport specified 
through transport. If broadcasting is not supported by any tran- 
sport, an error message is printed. Only UDP transports support 
broadcasting. 
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-d Delete registration for the RFC service of the specified program 

and x)ersion. If transport is specified, unregister the service on 
only that transport, otherwise unregister the services on all the 
transports on which it was registered. This option can be exer- 
cised only by the privileged user. 

-n Use portnum as the port nunlber for the -t and -u options 

instead of the port number given by the portmapper. Use of this 
option avoids a call to the remote portmapper to find out the 
address of the service. 

-p Probe the portmapper on host, and print a list of all registered 

RPC programs. If host is not specified, it defaults to the local 
host. 

-t Make an RPC call to procedure 0 of program on the specified host 

using TCP, and report whether a response was received. 

-u Make an J^PC call to procedure 0 of program on the specified host 

using UDP, and report whether a response was received. 

The program argument is a number. 

If a version is specified, rpcinf o attempts to call that version of the specified pro- 
gram. Otherwise, rpcinf o attempts to find all the registered version numbers for 
the specified program by calling version 0, which is presumed not to exist; if it 
does exist, rpcinf o attempts to obtain this information by calling an extremely 
high version number instead, and attempts to call each registered version. Note: 
the version number is required for -b and -d options. 

EXAMPLES 

To show all of the RPC services registered on the local machine use: 
$ rpcinf o 

To show all of the RPC services registered with rpcbind on the machine named 
klaxon use: 

$ rpcinfo klaxon 

To show if the RPC service with program number progjio and version vers is 
registered on the machine named klaxon for the transport tcp use: 

$ rpcinfo -T tcp klaxon progjio vers 

To show all of the RPC services registered with the portmapper on the local 
machine use: 

$ rpcinfo -p 

To ping version 2 of rpcbind (program number 100000) on host sparky: 
$ rpcinfo -t sparky 100000 2 
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To delete the registration for version 1 of the walld (program number 100008) 
service for all transports use: 

# rpcinfo -d 100008 1 

SEE ALSO 

rpcd^indClM), rpc(4). 
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NAME 

rpc . rusersd - network username server 
SYNOPSIS 

/usr/lib/netsvc/rusers/zpc . rusersd 
DESCRIPTION 

rusersd is a server that returns a list of users on the host. The rusersd daemon 
may be started by inetd(lM) or listen(lM). 

SEE ALSO 

inetdClM), listen(lM), pnadmClM), sacadxndM). 
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NAME 

rwall - write to all users over a network 

SYNOPSIS 

/usr/sbin/rwall hostname . . . 

DESCRIPTION 

rwall reads a message from standard input until EOF. It then sends this mes- 
sage, preceded by the line: 

Broadcast Message . . . 

to all users logged in on the specified host machines. 

A machine can only receive such a message if it is running rwalld(lM), which 
may be started by inetddM) or listen(lM). 

NOTES 

The timeout is fairly short to allow transmission to a large group of machines 
(some of which may be down) in a reasonable amount of time. Thus the message 
may not get through to a heavily loaded machine. 

SEE ALSO 

inetdClM), listen(lM), pnadmClM), rwallddM), sacadm(lM), wall(l) 
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NAME 

rpc . rwalld - network rwall server 

SYNOPSIS 

/usr/lib/netsvc/rwall/rpc . rwalld 

DESCRIPTION 

rwalld is a server that handles rwall(lM) requests. It is implemented by calling 
wall(lM) on all the appropriate network machines. The rwalld daemon may be 
started by inetddM) or listen(lM). 

SEE ALSO 

inetddM), listen(lM), rwall(lM), wall(lM). 
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NAME 

sac - service access controller 

SYNOPSIS 

sac -t sanity Jnterval 

DESCRIPTION 

The Service Access Controller (SAC) is the overseer of the server machine. It is 
started when the server machine enters miiltiuser mode. The SAC performs 
several important functions as explained below. 

Customizing the SAC environment. When sac is invoked, it first looks for the per- 
system configuration script /etc/saf /_sysconfig. sac interprets _sysconfig 
to customize its own environment. The modifications made to the SAC environ- 
ment by _sysconf ig are inherited by all the children of the SAC. This inherited 
environment may be modified by the children. 

Starting port monitors. After it has interpreted the _sysconf ig file, the sac reads 
its administrative file /etc/saf /_sactab. _sactab specifies which port monitors 
are to be started. For each port monitor to be started, sac forks a child [fork(2)] 
and creates a uturp entry with the type field set to LOGIN_PROCESS. Each child 
then interprets its per-port monitor configuration script 
/etc/saf /pwteg/_config, if the file exists. These modifications to the environ- 
ment affect the port monitor and will be inherited by all its children. Finally, the 
child process execs the port monitor, using the command found in the _sactab 
entry. (See sacadm; this is the command given with the -c option when the port 
monitor is added to the system.) 

Polling port monitors to detect failure. The -t option sets the frequency with which 
sac polls the port monitors on the system. This time may also be thought of as 
half of the maximum latency required to detect that a port monitor has failed and 
that recovery action is necessary. 

Administrative functions. The Service Access Controller represents the administra- 
tive point of control for port monitors. Its administrative tasks are explained 
below. 

When queried (sacadm with either -1 or -L), the Service Access Controller 
returns the status of the port monitors specified, which sacadm prints on the stan- 
dard output. A port monitor may be in one of six states: 

ENABLED The port monitor is currently running and is accepting connec- 

tions. See sacadm(lM) with the -e option. 

DISABLED The port monitor is currently running and is not accepting con- 

nections. See sacadm with the -d option, and see NOTRUNNING, 
below. 

STARTING The port monitor is in the process of starting up. STARTING is 

an intermediate state on the way to ENABLED or DISABLED. 

FAILED The port monitor was unable to start and remain running. 
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The port monitor has been manually terminated but has not 
completed its shutdown procedure. STOPPING is an intermedi- 
ate state on the way to N0TRUNNIN6. 

The port monitor is not currently running. (See sacadm with 
-k.) This is the normal "not running" state. When a port mon- 
itor is killed, all ports it was monitoring are inaccessible. It is 
not possible for aii external user to tell whether a port is not 
being monitored or the system is down. If the port monitor is 
not killed but is in the DISABLED state, it may be possible 
(depending on the port monitor being used) to write a message 
on the inaccessible port telling the user who is trying to access 
the port that it is disabled. This is the advantage of having a 
DISABLED state as well as the NOTRUNNING state. 

When a port monitor terminates, the SAC removes the utnp entry for that port 
monitor. 

The SAC receives all requests to enable, disable, start, or stop port monitors and 
takes the appropriate action. 

The SAC is responsible for restarting port monitors that terminate. Whether or 
not the SAC will restart a given port monitor depends on two things: 

- the restart count specified for the port monitor when the port monitor 
was added by sacadnv this information is included in 
/etc/saf/pntog/_sactab 

-- the nimiber of times the port monitor has already been restarted 

SEE ALSO 

sacadmClM), pnadxn(lM). 

FILES 

/etc/saf/jsactab 
/etc/saf/jsysconfig 
/var/adni/ut:np 
/var/saf/_log 
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NAME 

sacadm - service access controller administration 
SYNOPSIS 

sacadm -a -p jmtag -t type -c cmd -v ver [-f dx] [-n count] \ 
[-y comment] [-z script] 



sacadm 


-r 


-ppmtag 




sacadm 


-s 


Ippmtag 




sacadm 


-k 


-p pmtag 




sacadm 


-e 


-^pmtag 




sacadm 


-d 


pmtag 




sacadm 


-1 


i-p pmtag 1 


-ttype] 


sacadm 


-L 


{"V pmtag 1 


-t type] 


sacadm 




-ip pmtag hz 


script] 


sacadm 


HS 


[-Z script] 




sacadm 


-X 


[~p pmtag] 





DESCRIPTION 

sacadm is the administrative command for the upper level of the Service Access 
Facility hierarchy, that is, for port monitor administration, sacadm performs the 
following fimctions: 

- adds or removes a port monitor 

- starts or stops a port monitor 

- enables or disables a port monitor 

- installs or replaces a per-system configuration script 

- installs or replaces a per-port monitor configuration script 

- prints requested port monitor information 

Requests about the status of port monitors (-1 and -L) and requests to print per- 
port monitor and per-system configuration scripts (-g and without the -z 
option) may be executed by any user on the system. Other sacadm commands 
may be executed only by a privileged user. 

The options have the following meanings: 

-a Add a port monitor. When adding a port monitor, sacadm creates the 
supporting directory structure in /etc/saf and /var/saf and adds an 
entry for the new port monitor to /etc/saf /__sactab. The file _sactab 
already exists on the delivered system. Initially, it is empty except for a 
single line, which contains the version number of the Service Access 
Controller. 

Unless the command line that adds the new port monitor includes a -f 
option with the argument x, the new port monitor will be started. 
Because of the complexity of the options and arguments that follow the 
-a option, it may be convenient to use a command script or the menu 
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system to add port monitors. If you use the menu system, enter sysadm 
ports and then choose the port jnnonitors option. 

-c and Execute the command string and to start a port monitor. The -c option 
may be used only with a -a. A -a option requires a -c. 

-d Disable the port monitor ptntag, 

-e Enable the port monitor pmtag, 

-f dx The -f option specifies one or both of the following two flags which are 
then included in the flags field of the jsactab entry for the new port 
monitor. If the -f option is not included on the command line, no flags 
are set and the default conditions prevail. By default, a port monitor is 
started. A -f option with no following argument is illegal. 

d Do not enable the new port monitor. 
X Do not start the new port monitor. 

-g The -g option is used to request output or to install or replace the per- 
port monitor configuration script /etc/saf /pnteg/jconf ig. -g requires 
a -p option. The -g option with only a -p option prints the per-port 
monitor configuration script for port monitor pmtag. The -g option with 
a -p option and a -z option installs the file script as the per-port moni- 
tor configuration script for port monitor pmtag. Other combinations of 
options with -g are invalid. 

-G The -C option is used to request output or to install or replace the per- 
system configuration script /etc/saf/_sysconf ig. The -G option by 
itself prints the per-system configuration script. The -G option in combi- 
nation with a -z option installs the file script as the per-system 
configuration script. Other combinations of options with a ~G option are 
invalid. 

-k Stop port monitor pmtag. 

-1 The -1 option is used to request port monitor information. The -1 by 
itself lists all port monitors on the system. The -1 option in combination 
with the -p option lists only the port monitor specified by pmtag. A -1 
in combination with the -t option lists all port monitors of type type. 
Any other combination of options with the -1 option is invalid. 

-L The -L option is identical to the -1 option except that the output 
appears in a condensed format. 

-n count 

Set the restart count to count. If a restart count is not specified, count is 
set to 0. A count of 0 indicates that the port monitor is not to be res- 
tarted if it fails. 

-p pmtag 

Specifies the tag associated with a port monitor. 
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-r Remove port monitor pmtag. sacadm removes the port monitor entry 
from /etc/saf /jsactab. If the removed port monitor is not running, 
then no further action is taken. If the removed port monitor is running, 
the Service Access Controller (SAC) sends it SIGTEBM to indicate that it 
should shut down. Note that the port monitor's directory structure 
remains intact. 

-s Start a port monitor. The SAC starts the port monitor pmtag. 
-t type Specifies the port monitor type. 

-V ver Specifies the version number of the port monitor. This version number 
may be given as 

-V ^pmspec -V^ 

where pmspec is the special administrative command for port monitor 
pmtag. This special command is ttyadm for ttyinon and nlsadmin for 
listen. The version stamp of the port monitor is known by the com- 
mand and is returned when pmspec is invoked with a -V option. 

-X The -X option by itself tells the SAC to read its database file (__sactab). 
The -X option with the -p option tells port monitor pmtag to read its 
administrative file. 

-y comment 

Include comment in the jsactab entry for port monitor pmtag. 
-z script 

Used with the -g and -G options to specify the name of a file that con- 
tains a configuration script. With the -g option, script is a per-port 
monitor configuration script; with ~G it is a per-system configuration 
script. Modifying a configuration script is a three-step procedure. First 
a copy of the existing script is made (-g or -G). Then the copy is edited. 
Finally, the copy is put in place over the existing script (-g or -G with 

OUTPUT 

If successful, sacadm will exit with a status of 0. If sacadm fails for any reason, it 
will exit with a nonzero status. Options that request information will write the 
information on the standard output. In the condensed format (-U, port monitor 
information is printed as a sequence of colon-separated fields; empty fields are 
indicated by two successive colons. The standard format (-1) prints a header 
identifying the columns, and port monitor information is aligned imder the 
appropriate headings. In this format, an empty field is indicated by a hyphen. 
TTie comment character is #. 

EXAMPLES 

The following command line adds a port monitor. The port monitor tag is 
npack; its type is listen; if necessary, it will restart three times before failing; its 
administrative command is nlsadmin; and the configuration script to be read is 
in the file script: 

sacadm -a -p npack -t listen -c /usr/lib/saf/listen npack \ 
-V ^nlsadmin -V^ -n 3 -z script 
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Remove a port monitor whose tag is pmtag: 

sacadm -r -p pmtag 
Start the port monitor whose tag is ptntag: 

sacadm ~s ~p pmtag 
Stop the port monitor whose tag is pmbag: 

sacadm -k ~p pmt:ag 
Enable the port monitor whose tag is pmtag: 

sacadm -e -p pmtag 
Disable the port monitor whose tag is pmtag: 

sacadm -d -p pmtag 
List status information for all port monitors: 

sacadm -1 

List status information for the port monitor whose tag is pmtag: 

sacadm -1 -p pmtag 
List the same information in condensed format: 

sacadm -L ~p pmtag 
List status information for all port monitors whose type is listen: 

sacadm -1 -t listen 

Replace the per-port monitor configuration script associated with the port moni- 
tor whose tag is pmtag with the contents of the file file . conf ig: 

sacadm -g -p pmtag -z file . conf ig 

SEE ALSO 

doconf ig(3N), pmadm(lM), sac(lM). 

FILES 

/etc/saf/__sactab 
/etc/ saf / jsysconf ig 
/etc/saf/pmteg/jconfig 



Page 4 



10/89 



spray (1M) 



spray (1M) 



NAME 

spray - spray packets 
SYNOPSIS 

/usr/sbin/spray [ -c count ] [ -d delay ] [ -1 length ] [ -t nettype host ] 
DESCRIPTION 

spray sends a one-way stream of packets to host using RPC, and reports how 
many were received, as well as the the transfer rate. The host argument can be 
either a name or an Internet address. 

The following options are available: 

-c count Specify how many packets to send. The default value of count is 

the number of packets required to make the total stream size 
100000 bytes. 

-d delay Specify how many microseconds to pause between sending each 

packet. The default is 0. 

-1 length The length parameter is the numbers of bytes in the Ethernet 

packet that holds the RFC call message. Since the data is 
encoded using XDR, and XDR only deals with 32 bit quantities, 
not all values of length are possible, and spray roimds up to the 
nearest possible value. When length is greater than 1514, then the 
RFC call can no longer be encapsulated in one Ethernet packet, so 
the length field no longer has a simple correspondence to Ether- 
net packet size. The default value of length is 86 bytes (the size 
of the RFC and UDP headers). 

-t nettype Specify clas of transports. Defaults to netpath. See rpc(3ND for 
a description of supported classes. 

SEE ALSO 

sprayddM), rpc(3hD 
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NAME 

rpc . sprayd - spray server 

SYNOPSIS 

/usr/lib/netsvc/spray/rpc . sprayd 

DESCRIPTION 

rpc. sprayd is a server which records the packets sent by spray(lM). The 
rpc. sprayd daemon may be started by inetddM) or listendM). 

SEE ALSO 

inetddM) listendM), pnadndM), sacadmClM), spraydM) 
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NAME 

ypinit - build and install YP database 

SYNOPSIS 

/usr/sbin/ypinit -c 
/usr/sbin/ypinit -m 
/usr/sbin/ypinit -s master-name 

DESCRIPTION 

ypinit sets up a YP name service database on a YP server. It can be used to set 
up a master or a slave server, or a client system. You must be the privileged user 
to nm it. It asks a few, self-explanatory questions, and reports success or failure 
to the terminal. 

It sets up a master server using the simple model in which that server is master 
to all maps in the data base. This is the way to bootstrap the YP system; later if 
you want you can change the association of maps to masters. 

All databases are built from scratch, either from information available to the pro- 
gram at runtime, or from the ASQI data base files in /etc. These files should be 
in their traditional form, rather than the abbreviated form used on client 
machines. 

A YP database on a slave server is set up by copying an existing database from a 
running server. The master-name argument should be the hostname of a YP server 
(either the master server for all the maps, or a server on which the data base is 
up-to-date and stable). 

To set up a client, ypinit prompts for a list of YP servers to bind the client to, this 
list should be ordered from closest to farthest server. 

Read ypf iles(4) and ypserv(lM) for an overview of the YP name service. 

The following options are available: 

-c Set up a client system. 

-m Indicate that the local host is to be the YP master. 

-s master-name 

Set up a slave database. 

SEE ALSO 

inakedbmdM), ypmake(lM), yppush(lM), ypserv(lM), ypxfr(lM), ypf iles(4) 

FILES 

/vax/yp/hindiiig/domainname/ypservera 
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NAME 

ypinake - rebuild YP database 

SYNOPSIS 

cd /var/yp ; make [ map ] 

DESCRIPTION 

The file called Makefile in /var/yp is used by make to build the YP name ser- 
vice database. With no arguments, make creates dbm databases for any YP maps 
that are out-of-date, and then executes yppushClM) to notify slave databases that 
there has been a change. 

If map is supplied on the command line, make will update that map only. 

There are three special variables used by make: DIR, which gives the directory of 
the source files; NOPUSH, which when non-null inhibits doing a yppush of the 
new database files; and DOM, used to construct a domain other than the master's 
default domain. The default for DIR is /etc, and the default for NOPUSH is the 
null string. 

ypmake also creates an entry in /var/yp/aliases. 

Refer to yp£iles(4) and ypserv(lM) for an overview of the YP. 

FILES 

/var/yp 
SEE ALSO 

make(l), makedbin(lM), yppush(lM), ypserv(lM), ypf iles(4) 
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NAME 

yppoll - return current version of a YP map at a YP server host 
SYNOPSIS 

/usr/sbin/yppoll [ -d ypdomain ] [ -h host ] mapname 
DESCRIPTION 

The yppoll command asks a ypserv(lM) process what the order number is, and 
which host is the master YP server for the named map. 

The following options are available: 

-d ypdomain 

Use ypdomain instead of the default domain. 

-h host 

Ask the ypserv process at host about the map parameters. If host is not 
specified, the YP server for the local host is used. That is, the default host 
is the one returned by ypwhich(l). 

SEE ALSO 

ypserv(lM), yp^^ichd), ypf iles(4) 
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NAME 



yppush - force propagation of a changed YP map 



SYNOPSIS 



/usr/sbin/yppush [ -v ] [ -d ypdomain ] mapname 



DESCRIPTION 



yppush copies a new version of a YP name service map from the master YP 
server to the slave YP servers. It is normally run only on the master YP server by 
the Makefile in /var/yp after the master databases are changed. It first con- 
structs a list of YP server hosts by reading the YP map ypservers within the 
ypdomain, or if the map is not set up, the local file is used. Keys within the map 
ypservers are the ASQI n^mes of the machines on which the YP servers run. 

A transfer map request is sent to the YP server at each host, along with the infor- 
mation needed by the transfer agent (the program which actually moves the map) 
to call back the yppush . When the attempt has completed (successfully or not), 
and the transfer agent has sent yppush a status message, the results may be 
printed to stdout. Messages are also printed when a transfer is not possible; for 
instance when the request message is undeliverable, or when the timeout period 
on responses has expired. 

Refer to ypf iles(4) and ypserv(lM) for an overview of the YP name service. 
The following optionas are available: 

-V Verbose. Print messages when each server is called, and for each 
response. If this flag is omitted, only error messages are printed. 

-d ypdomain 

Specify a ypdomain other than the default domain. 



FILES 



/var/yp/ypdomain/ypservers . {dir,pag} 
/var/yp 



local file 



SEE ALSO 



ypserv(lM), ypxf r(lM), ypf iles(4) 
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NAME 

ypserv, ypbind - YP server and binder processes 

SYNOPSIS 

/usr/lib/netsvc/yp/ypserv 

/usr/lib/netsvc/yp/ypbind [ -ypset | -ypsetne ] 
DESCRIPTION 

The YP provides a simple network lookup service consisting of databases and 
processes. The databases are dbni(3) files in a directory tree rooted at /var/yp. 
These files are described in ypfiles(4). The processes are /usr/sbin/ypserv, 
the YP database lookup server, and /usr/sbin/ypbind, the YP binder. The pro- 
grammatic interface to YP is described in ypclnt(3N). Administrative tools are 
described in yppushdM), ypxfrdM), yppoll(lM), ypwhich(l), and ypset(lM). 
Tools to see the contents of YP maps are described in ypcat(l), and ypnatchd). 
Database generation and maintenance tools are described in ypinit(lM), 
yproake(lM), and xnakedbnidM). 

Both ypserv and ypbind are daemon processes typically activated at system 
startup time from /etc/rc. local, ypserv runs only on YP server machines with 
a complete YP database, ypbind runs on all machines using YP services, both YP 
servers and clients. 

The ypserv daemon's primary function is to look up information in its local data- 
base of YP maps. Communication to and from ypserv is by means of RPC calls. 
Lookup fimctions are described in ypclntON)/ and are supplied as C-callable 
fimctions in the YP library. There are four lookup fimctions, all of which are per- 
formed on a specified map within some YP domain: Match, "Getjirst", "Getjtext", 
and "Getjiir. The Match operation takes a key, and returns the associated value. 
The "Getjirst" operation returns the first key-value pair from the map, and 
"Getjtext" can be used to entimerate the remainder. "Get air ships the entire 
map to the requester as the response to a single RPC request. 

Two other fimctions supply information about the map, rather than map entries: 
"Getjyrderjtumber", and "Getjnasterjtame", In fact, both order number and mas- 
ter name exist in the map as key-value pairs, but the server will not return either 
through the normal lookup functions. If you examine the map with 
makedbindM), however, they will be visible. 

The function of ypbind is to remember information that lets client processes on a 
single node communicate with some ypserv process, ypbind must run on every 
machine which has YP client processes; ypserv may or may not be nmning on 
the same node, but must be nmning somewhere on the network. 

The information ypbind remembers is called a binding — the association of a 
domain name with a YP server. 

The process of binding is driven by client requests. As a request for an unbound 
domain comes in, the ypbind process steps through the ypservers list (last entry 
first) trying to find a ypserv process that serves maps within that domain. There 
must be a ypserv process on at least one of the hosts in the ypservers file. 
Once a domain is bound by a particular ypbind, that same binding is given to 
every client process on the node. The ypbind process on the local node or a 
remote node may be queried for the binding of a particular domain by using the 
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ypwhich(l) command. 

If ypbind is imable to speak to the :ypserv process it is boimd to, it marks the 
domain as unboimd, tells the client process that the domain is unbound, and tries 
to bind the domain once again. Requests received for an unbound domain will 
wait imtil the domain requested is bound. In general, a boimd domain is marked 
as unbound when the node running ypserv crashes or gets overloaded. In such 
a case, ypbind will to bind another YP server listed in 
/var/yp/hinding/dotnainname/ypaervera, 

ypbind also accepts requests to set its binding for a particular domain. The 
request is usually generated by the YP subsystem itself. ypset(lM) is a command 
to access the "Setjiomain'* facility. Note: the Set Domain procedure only accepts 
requests from processes running as root, ant the -ypset or -ypsetme flags must 
have been set for ypbind. 

The following options are available for the yjdDind command only: 

-ypset Allow any user to call ypset(lM). By default, no one can call 
ypset(lM). 

-ypsetme Only allow root on local machines to call ypset(lM). By default, 
no one can call ypset(lM). 

FILES 

If the file /var/yp/ypserv.log exists when ypserv starts up, log information 

will be written to this file when error conditions arise. 

/var/yp 

/var/yp/binding/yp^owwzn/ypservers 
SEE ALSO 

roakedbxn(lM), ypcat(l), ypinit(lM), ypxnake(lM), ypmatchd), yppoll(lM), 
yppush(lM), ypset(lM), ypwhichd), ypxfr(lM), dbn<3X), ypclnt(3N), 
ypfiles(4) 

NOTES 

Both ypbind and ypserv support multiple domains. The ypserv process deter- 
mines the domains it serves by looking for directories of the same name in the 
directory /var/yp. Additionally, the ypbind process can maintain bindings to 
several domains and their servers. 
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NAME 

ypset - point ypbind at a particular server 
SYNOPSIS 

/usr/sbin/ypset [ -d ypdormin ] [ -h host ] server 
DESCRIPTION 

In order to run ypset, ypbind must be initiated with the -ypset or -ypsetine 
options. See ypserv(lM). ypset tells ypbind to get YP services for the specified 
ypdoimin from the ypserv process running on server. If server is down, or is not 
running ypserv, this is not discovered until a YP client process tries to get a bind- 
ing for the domain. At this point, the binding set by ypset will be tested by 
ypbind. If the binding is invalid, ypbind will attempt to rebind for the same 
domain. 

ypset is useful for binding a client node which is not on a broadcast net, or is on 
a broadcast net which is not running a YP server host. It also is useful for debug- 
ging YP dient applications, for instance where a YP map only exists at a single YP 
server host. 

In cases where several hosts on the local net are supplying YP services, it is possi- 
ble for ypbind to rebind to another host even while you attempt to find out if the 
ypset operation succeeded. For example, you can type: 

% ypset hostl 

% ypvdiich 

host2 

which can be confusing. This is a function of the YP subsystem's attempt to 
load-balance among the available YP servers, and occurs when hostl does not 
respond to ypbind because it is not running ypserv (or is overloaded), and hostl, 
running ypserv, gets the binding. 

server indicates the YP server to bind to, and must be specified as a name. This 
will work only if the node has a current valid binding for the domain in question, 
and ypbind has been set to allow use of ypset. In most cases, server should be 
specified as an IP address. 

ypset tries to bind ypbind over a datagram transport first. Datagram Transports 
are recommended for higher performance. The YP library calls, yp_enum(), 
yp_all ( ) , yp_next ( ) , and yp_f irst ( ) use circuit transports regardless of the 
main transport being used. 

Refer to ypf iles(4) and ypserv(lM) for an overview of the YP name service. 
The following options are available: 

"hhost Set ypbind's binding on host, instead of locally, host must be 

specified as a name. 

-d ypdoimin Use ypdomain , instead of the default domain. 

SEE ALSO 

ypserv(lM), yp^diichd), ypf iles(4) 
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NAME 

ypupdated - server for changing YP information 
SYNOPSIS 

/usr/lib/netsvc/yp/ypupdated [ -is ] 
DESCRIPTION 

ypupdated is a daemon that updates information in the YP name service, nor- 
mally started up by inetd(lM). ypupdated consults the file updaters(4) in the 
directory /var/yp to determine which YP maps should be updated and how to 
change them. 

By default, the daemon requires the most secure method of authentication avail- 
able to it, either DES (secure) or UNIX (insecure). 

The following options are available: 

-i Accept RPC calls with the insecure AUTH^UNIX credentials. This allows 
programmatic updating of YP maps in all networks. 

-s Only accept calls authenticated using the secure RPC mechanism 
(AUTH^DES authentication). This disables programmatic updating of YP 
maps unless the network supports these calls. 

FILES 

/var/yp/updaters 

SEE ALSO 

inetd(lM), keyse2:v(lM), i5>daters(4) 
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NAME 

ypxf r - transfer YP map from a YP server to host 
SYNOPSIS 

/usr/sbin/ypxf r [ -c ] [ -f ] [ -d ypdomain ] [ -h host ] [ -s ypdomain ] 
I -C tid prog server ] mapname 

DESCRIPTION 

The ypxf r command moves a YP map in the default domain for the local host to 
the local host by making use of normal YP services. It creates a temporary map 
in the directory /^jar/yg/ ypdomain (this directory must already exist; ypdomain is 
the default domain for the local host), fills it by enumerating the map's entries, 
fetches the map parameters (master and order number), and loads them. It then 
deletes any old versions of the map and moves the temporary map to the real 
mapname. 

If rim interactively, ypxfr writes its output to the terminal. However, if it is 
started without a controlling terminal, and if the log file /var/yp/ypxf r . log 
exists, it appends all its output to that file. Since ypxfr is most often run from the 
privileged user's crontab file, or by ypserv, the log file can be used to retain a 
record of what was attempted, and what the results were. 

For consistency between servers, ypxfr should be nm periodically for every map 
in the YP data base. Different maps change at different rates: a map may not 
change for months at a time, for instance, and may therefore be checked only 
once a day. Some maps may change several times per day. In such a case, you 
may want to check hourly for updates. A crontabd) entry can be used to per- 
form periodic updates automatically. Rather than having a separate crontab 
entry for each map, you can group comands to update several maps in a shell 
script. Examples (mnemonically named) are in /usr/sbin/yp: ypxfr^lperday, 
and ypxf r_lperhour. They can serve as reasonable first cuts. 

Refer to ypf iles(4) and ypserv(lM) for an overview of the YP name service. 

The following options are available: 

-c Do not send a Clear current map request to the local ypserv process. Use 
this flag if ypserv is not running locally at the time you are running 
ypxfr. Otherwise, ypxfr complains that it cannot talk to the local 
ypserv, and the transfer fails. 

-f Force the transfer to occur even if the version at the master is not more 
recent than the local version. 

-C tid prog server 

This option is only for use by ypserv. When ypserv starts ypxfr, it 
specifies that ypxfr should call back a yppush process at the host server, 
registered as program number prog, and waiting for a response to transac- 
tion tid, 

-d ypdomain 

Specify a domain other than the default domain. 
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-h host 

Get the map from host, regardless of what the map says the master is. If 
host is not specified, ypxf r asks the YP service for the name of the master, 
and try to get the map from there, host must be a name. 

-s ypdomain 

Specify a source domain from which to transfer a map that should be the 
same across domains. 



FILES 



/var/yp/ypxf r . log 
/usr/sbin/yp/ypxfr_lperday 



log file 

script to run one transfer per day, for use 
with cron(lM) 

script for hourly transfers of volatile maps 
YP domain 

privileged user's crontab file 



/usr/sbin/yp/ypxfr_lperhour 

/var/yp/ypdotmin 

/usr/spool/cron/crontabs/root 



SEE ALSO 



crondM), crontab(l), ypserv(lM), yppush(lM), ypf iles(4) 
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NAME 

dObm, dbminit, dbmclose^ fetch^ store^ delete, firstkey, nextkey - 
database subroutines 

SYNOPSIS 

♦include <dbm.h> 

typedef struct { 
char *dptr; 
int dsize; 
} datvim; 

dbminit(file) 
char *file; 
dbmclose ( ) 

datum fetch (key) 
datum key; 

store (key, content) 
datum key, content; 

delete (key) 
datimi key; 

datum f irstkey ( ) 

datum nextkey (key) 
datum key; 

DESCRIPTION 

These functions maintain key/ content pairs in a database. The functions will 
handle very large (a billion blocks) databases and will access a keyed item in one 
or two file system accesses. The functions are obtained with the loader option 
-lyp. 

keys and contents are described by the datum typedef. A datum specifies a string 
of dsize bytes pointed to by dptr. Arbitrary binary data, as well as normal ASQI 
strings, are allowed. The database is stored in two files. One fQe is a directory 
containing a bit map and has .dir as its suffix. The second file contains all data 
and has .pag as its suffix. 

Before a database can be accessed, it must be opened by dbminit. At the time of 
this call, the files file. dir and file. pag must exist. An empty database is created 
by creating zero-length .dir and .pag files. 

A database may be closed by calling dbmclose. You must close a database 
before opening a new one. 

Once open, the data stored under a key is accessed by fetch ( ) and data is 
placed under a key by store. A key (and its associated contents) is deleted by 
delete. A linear pass through all keys in a database may be made, in an 
(apparently) random order, by use of firstkeyO and nextkey. firstkeyO 
will return the first key in the database. With any key nextkey ( ) will return the 
next key in the database. This code will traverse the database: 

for (key = firstkeyO; key. dptr != NULL; key = nextkey (key) ) 
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RETURN VALUE 

All functions that return an int indicate errors with negative values. A zero 
return indicates no error. Routines that return a datum indicate errors with a 
NULL (0) dptr, 

NOTES 

The .pag file will contain holes so that its apparent size is about four times its 
actual content. Older versions of the UNIX operating system may create real file 
blocks for these holes when touched. These files cannot be copied by normal 
means (cp(l), cat(l), tar(l), ar(l)) without filling in the holes. 

dptr pointers returned by these subroutines point into static storage that is 
changed by subsequent calls. 

The sum of the sizes of a key /content pair must not exceed the internal block size 
(currently 1024 bytes). Moreover all key /content pairs that hash together must fit 
on a single block, store ( ) will return an error in the event that a disk block fills 
with inseparable data. 

delete ( ) does not physically reclaim file space, although it does make it avail- 
able for reuse. 

The order of keys presented by firstkey( ) and nextkey( ) depends on a hash- 
ing function, not on anything interesting. 

There are no interlocks and no reliable cache flushing; thus concurrent updating 
and reading is risky. 

FILES 

/usr/lib/libyp . a 
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NAME 

select - synchronous I/O multiplexing 

SYNOPSIS 

♦include <sys/tirne.h> 
♦include <sys/types . h> 

select (nfds, readfds^ writefds^ execptfds, timeout) 
int nfds; 

fd_set *readfds, *writefds, *execptfds; 
struct timeval * timeout; 

FD_SET(fd, fifdset); 
FD_CLR(fd, fifdset); 
FD_ISSET(fd, fifdset); 
FD_ZERO(&fdset)/ 
int fd; 
fd_set fdset; 

DESCRIPTION 

select examines the I/O descriptor sets whose addresses are passed in readfds, 
writefds, and execptfds to see if any of their descriptors are ready for reading, are 
ready for writing, or have an exceptional condition pending, respectively, nfds is 
the number of bits to be checked in each bit mask that represents a file descriptor; 
the descriptors from 0 to -1 in the descriptor sets are examined. On return, 
select replaces the given descriptor sets with subsets consisting of those descrip- 
tors that are ready for the requested operation. The return value from the call to 
select 0 is the number of ready descriptors. 

The descriptor sets are stored as bit fields in arrays of integers. The following 
macros are provided for manipulating such descriptor sets: FD_ZERO {Scfdset) ini- 
tializes a descriptor set fdset to the null set. FDjSET(//i^ Sifdset) includes a partic- 
ular descriptor fd in fdset. FDjCLR(/i, Stfdset) removes fd from fdset. 
FD_ISSET(/^, Stfdset) is nonzero if fd is a member of fdset, zero otherwise. The 
behavior of these macros is undefined if a descriptor value is less than zero or 
greater than or equal to FD_SETSIZE. Fp__SETSIZE is a constant defined in 
sys/select .h and is normally at least equal to the maximum nimiber of descrip- 
tors supported by the system. 

If timeout is not a NULL pointer, it specifies a maximum interval to wait for the 
selection to complete. If timeout is a NULL pointer, the select blocks indefinitely. 
To affect a poll, the timeout argument should be a non-NULL pointer, pointing to 
a zero-valued timeval structure. 

Any of readfds, writefds, and execptfds may be given as NULL pointers if no 
descriptors are of interest. 

RETURN VALUE 

select returns the number of ready descriptors contained in the descriptor sets 
or -1 if an error occurred. If the time limit expires, then select returns 0. 
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ERRORS 

An error return from select indicates: 

EBADF One of the I/O descriptor sets specified an invalid I/O descriptor. 

EINra A signal was delivered before any of the selected events 

occurred, or the time limit expired. 

EINV3^ A component of the pointed-to time limit is outside the accept- 

able range: tjsec must be between 0 and 10®, inclusive, tjusec 
must be greater-than or equal to 0, and less than 10^. 

SEE ALSO 

poll(2), read(2), write(2) 

NOTES 

The default value for FD_SETSIZE (currently 1024) is larger than the default limit 
on the nimiber of open files. In order to accommodate programs that may use a 
larger number of open files with select, it is possible to increase this size within 
a program by providing a larger definition of FD_SETSIZE before the inclusion of 
<sys/types.h>. 

In future versions of the system, select may return the time remaining from the 
original timeout, if any, by modifying the time value in place. It is thus imwise 
to assume that the timeout value will be unmodified by the select call. 

The descriptor sets are always modified on return, even if the call returns as the 
result of a timeout. 



Page 2 



10/89 



accept (3N) 



accept (3N) 



NAME 

accept - accept a connection on a socket 

SYNOPSIS 

finclude <sys/types.h> 
♦include <sys/socket.h> 

ns - accept (s^ addr, addrlen) 
int ns, s; 

struct sockaddr *addr; 
int *addrlen; 

DESCRIPTION 

The argument s is a socket that has been created with socketON) and bound to 
an address with bind(3N), and that is listening for connections after a call to 
listenON). acceptC ) extracts the first connection on the queue of pending con- 
nections, creates a new socket with the properties of s, and allocates a new file 
descriptor, ns, for the socket. If no pending connections are present on the queue 
and the socket is not marked as non-blocking, acceptO blocks the caller until a 
connection is present. If the socket is marked as non-blocking and no pending 
connections are present on the queue, acceptO returns an error as described 
below. accept( ) uses the netconf icf(4) file to determine the STREAMS device file 
name associated with s. This is the device on which the connect indication will be 
accepted. The accepted socket, ns, is used to read and write data to and from the 
socket that connected to ns; it is not used to accept more connections. The origi- 
nal socket (s) remains open for accepting further connections. 

The argument addr is a result parameter that is filled in with the address of the 
connecting entity as it is known to the communications layer. The exact format 
of the addr parameter is determined by the domain in which the communication 
occurs. 

addrlen is a value-result parameter. Initially, it contains the amount of space 
pointed to by addr; on return it contains the length in bytes of the address 
returned. 

acceptO is used with connection-based socket types, currently with 
SOCKJSTREAM. 

It is possible to select(3N) a socket for the purpose of an accept( ) by selecting 
it for read. However, this will only indicate when a connect indication is pend- 
ing; it is still necessary to call acceptO. 

RETURN VALUE 

acceptO returns -1 on error. If it succeeds, it returns a non-negative integer that 
is a descriptor for the accepted socket. 

ERRORS 

acceptC ) will fail if: 

EBADF The descriptor is invalid. 

ENOTSOCK The descriptor does not reference a socket. 
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EOPNOTSUPP The referenced socket is not of type SOCK_STREAM. 

EWOULDBLOCK The socket is marked as non-blocking and no connections 

are present to be accepted. 

EPROTO A protocol error has occurred; for example^ the STREAMS 

protocol stack has not been initialized. 

ENODEV The protocol family and type corresponding to s could not 

be found in the netconf ig file. 

ENOMEM There was insufficient user memory available to complete 

the operation. 

ENOSR There were insufficient STREAMS resources available to 

complete the operation. 

SEE ALSO 

bind(3N), connect(3N), listenON), socketON), netconfig(4). 



Page 2 



10/89 



blnd(3N) 



blnd(3N) 



NAME 

bind - bind a name to a socket 

SYNOPSIS 

finclude <sys/types . h> 
finclude <sys/socket.h> 

bind(s, name, namelen) 
int s; 

struct soclcaddr *naine; 
int namelen; 

DESCRIPTION 

bindO assigns a name to an unnamed socket. When a socket is created with 
socket (3N)/ it exists in a name space (address family) but has no name assigned. 
bind() requests that the name pointed to by name be assigned to the socket. 

NOTES 

Binding a name in the UNIX domain creates a socket in the file system that must 
be deleted by the caller when it is no longer needed (using unlink(2)). 

The rules used in name binding vary between communication domains. 

RETURN VALUE 

If the bind is successful, a 0 value is returned. A return value of -1 indicates an 
error, which is further specified in the global errno. 

ERRORS 

The bindO call will fail if: 

EBADF s is not a valid descriptor. 

ENOTSOCK s is a descriptor for a file, not a socket. 

EADDRNOTAVAIL The specified address is not available on the local machine. 

EADDRINUSE The specified address is already in use. 

EINVAL namelen is not the size of a valid address for the specified 

address family. 

EINVAL The socket is already bound to an address. 

EACCES The requested address is protected and the current user has 

inadequate permission to access it. 

ENOSR There were insufficient STREAMS resources for the operation 

to complete. 

The following errors are specific to binding names in the UNIX domain: 

ENOTDIR A component of the path prefix of the pathname in name is 

not a directory. 

ENOENT A component of the path prefix of the pathname in name 

does not exist. 

EACCES Search permission is denied for a component of the path 

prefix of the pathname in name. 
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EWOP Too many s5anbolic links were encountered in translating 

the pathname in name. 

EIO An I/O error occurred while making the directory entry or 

allocating the inode. 

EROFS The inode would reside on a read-only file system. 

EISDIR A null pathname was specified. 

SEE ALSO 

unlink(2) 
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NAME 

byteorder, htonl, htons, ntohl, ntohs - convert values between host and 
network byte order 

SYNOPSIS 

♦include <sys/types.h> 
tinclude <netinet/in . h> 

netlong = htonl (hostlong) / 
u^long netlong, hostlong; 

net short = htons (host short) / 
u_short netshort, host short; 

hostlong = ntohl (netlong) ; 
u_long hostlong, netlong; 

host short = ntohs (netshbrt) ; 
u_short host short, netshort; 

DESCRIPTION 

These routines convert 16 and 32 bit quantities between network byte order and 
host byte order. On some architectures these routines are defined as NULL macros 
in the include file <netinet/in.h>. On other architectures, if their host byte 
order is different from network byte order, these routines are functional. 

These routines are most often used in conjunction with Internet addresses and 
ports as returned by gethostentON) and getservent(3N). 
SEE ALSO 

gethostent(3N), getservent(3hD 



10/89 



Page 1 



connect (3N) 



connect (3N) 



NAME 

connect - initiate a connection on a socket 

SYNOPSIS 

♦include <sys/types.h> 
♦include <sys/socket.h> 

connect (s, name, namelen) 
int s; 

struct sockaddr *naine; 
int namelen; 

DESCRIPTION 

The parameter s is a socket. If it is of type SOCKJDGRMi connect () specifies the 
peer with which the socket is to be associated; this address is the address to 
which datagrams are to be sent if a receiver is not explicitly designated; it is the 
only address from which datagrams are to be received. If the socket s is of t5^e 
SOCKJSTREA^^ connect () attempts to make a connection to another socket. The 
other socket is specified by name, name is an address in the communications 
space of the socket. Each communications space interprets the name parameter in 
its own way. If s is not bound, then it will be bound to an address selected by the 
underlying transport provider. Generally, stream sockets may successfully con- 
nect () only once; datagram sockets may use connect () multiple times to 
change their association. Datagram sockets may dissolve the association by con- 
necting to a null address. 

RETURN VALUE 

If the connection or binding succeeds, then 0 is returned. Otherwise a -1 is 
returned and a more specific error code is stored in errno. 



ERRORS 



The call fails if: 



EBADF 



s is not a valid descriptor. 



ENOTSOCK 



s is a descriptor for a file, not a socket. 



EADDRNOTAVAIL 



EINVMi 



namelen is not the size of a valid address for the specified 
address family. 

The specified address is not available on the remote 
machine. 



EISCCMi 



EAFNOSUPPORT 



Addresses in the specified address family cannot be used 
with this socket. 

The socket is already connected. 



ETIMEDOUT 



Connection establishment timed out without establishing a 
connection. 



ECONNREFUSED 



The attempt to connect was forcefully rejected. The calling 
program should close(2) the socket descriptor, and issue 
another socketON) call to obtain a new descriptor before 
attempting another connect 0 call. 
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ENETUMREACH The network is not reachable from this host. 

EADDRINUSE The address is already in use. 

EINPROGRESS The socket is non-blocking and the connection cannot be 

completed immediately. It is possible to select(3N) for 
completion by selecting the socket for writing. However, 
this is only possible if the socket STREAMS module is the 
topmost module on the protocol stack with a write service 
procedure. This will be the normal case. 

EALREADY The socket is non-blocking and a previous connection 

attempt has not yet been completed. 

EINTR The connection attempt was interrupted before any data 

arrived by the delivery of a signal. 

ENOTSOCK The file referred to by name is not a socket. 

EPROTOTYPE The file referred to by name is a socket of a type other than 

type s (for example, s is a SOCK_DGRAM socloet, while name 
refers to a SOCK_STREAM socket). 

ENOSR There were insufficient STREAMS resources available to com- 

plete the operation. 

The following errors are specific to connecting names in the UNIX domain. These 
errors may not apply in future versions of the UNIX IPC domain. 

ENOTDIR A component of the path prefix of the pathname in name is 

not a directory. 

A component of the path prefix of the pathname in name 
does not exist. 

The socket referred to by the pathname in name does not 
exist. 



ENOENT 



ENOENT 



EACCBS 



Search permission is denied for a component of the path 
prefix of the pathname in name. 

Too many symbolic links were encountered in translating 
the pathname in name. 

An I/O error occurred while reading from or writing to the 
file system. 

SEE ALSO 

acceptON), cdnnectON)/ getsocknameON), socketON). 



ELOC^ 



EIO 
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NAME 

dial - establish an outgoing terminal line connection 

SYNOPSIS 

♦include <dial.h> 

int dial (CALL call) ; 
void undial (int fd> ; 
DESCRIPTION 

dial returns a file-descriptor for a terminal line open for read/write. The argu- 
ment to dial is a CALL structure (defined in the dial .h header file). 

When finished with the terminal line, the calling program must invoke imdial to 
release the semaphore that has been set during the allocation of the terminal dev- 
ice. 

The definition of CALL in the dial.h header file is: 
typedef struct { 

struct termio *attr; /* pointer to termio attribute struct ♦/ 
int baud; /i* transmission data rate 

int speed; /* 212A modem: low*300, high-1200 */ 

char *line; /* device name for out -going line */ 

char *telno; /* pointer to tel-no digits string */ 

int modem; specify mod»a control for direct lines 

char ^device; /* unused */ 

int dev_len; /* unused */ 

> CALL; 

The CALL element speed is intended only for use with an outgoing dialed call, in 
which case its value should be either 300 or 1200 to identify the 113A modem, or 
the high- or low-speed setting on the 212A modem. Note that the 113A modem 
or the low-speed setting of the 21 2A modem will transmit at any rate between 0 
and 300 bits per second. However, the high-speed setting of the 212 A modem 
transmits and receives at 1200 bits per second only. The CALL element baud is for 
the desired transmission baud rate. For example, one might set baud to 110 and 
speed to 300 (or 1200). However, if speed is set to 1200, baud must be set to 
high (1200). 

If the desired terminal line is a direct line, a string pointer to its device-name 
should be placed in the line element in the CALL structure. Legal values for 
such terminal device names are kept in the Devices file. In this case, the value of 
the baud element should be set to -1. This value will cause dial to determine the 
correct value from the Devices file. 

The telno element is for a pointer to a character string representing the tele- 
phone number to be dialed. Such mmibers may consist only of these characters: 

0-9 dial 0-9 

* dial * 

# dial # 

= wait for secondary dial tone 

- delay for approximately 4 seconds 
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The CALL element modem is used to specify modem control for direct lines. This 
element should be non-zero if modem control is required. The CALL element 
attr is a pointer to a termio structure, as defined in the termio . h header file. 
A NULL value for this pointer element may be passed to the dial fimction, but if 
such a structure is included, the elements specified in it will be set for the outgo- 
ing terminal line before the connection is established. This setting is often impor- 
tant for certain attributes such as parity and baud-rate. 

The CALL elements device and dev_len are no longer used. They are retained in 
the CALL structure for compatibility reasons. 

FILES 

/etc/uucp/Devices 
/etc/uucp/Systems 
/var/spool/uucp/LCK. Aty-devke 

SEE ALSO 

alarm(2), read(2), write(2). 

termio(7) in the System Administrator's Reference Manual, 
uucp(lC) in the User's Reference Manual, 
DIAGNOSTICS 

On failure, a negative value indicating the reason for the failure will be returned. 
Mnemonics for these negative indices as listed here are defined in the dial.h 
header file. 



INTENT 


-1 


/* 


interrupt ocscurred */ 


DJJUNG 


-2 


/♦ 


dialer hung (no return from write) */ 


N0_ANS 


-3 


/* 


no anstPer within 10 seconds *J 


nJi_BD 


-4 


/* 


illegal baud-rate */ 


AJPROB 


-5 


/* 


acu problem (openO failure) */ 


L_PROB 


-6 


/* 


line problem (openO failure) */ 


N0_Jidv 


-7 


/* 


can't open Devices file */ 


DVJ1T_A 


-8 


/* 


requested device not available */ 


DV_NT_K 


-9 


/* 


requested device not known */ 




-10 


/♦ 


no device available at requested baud */ 


NOJBDJC 


-11 


/* 


no device known at requested baud */ 


DVJITja 


-12 


/* 


requested speed does not match */ 


BADJ5YS 


-13 


/* 


system not in Systons file*/ 



NOTES 

Including the dial.h header file automatically includes the termo.h header file. 

An alann(2) system call for 3600 seconds is made (and caught) within the dial 
module for the purpose of "touching" the LCK. . file and constitutes the device 
allocation semaphore for the terminal device. Otherwise, uucp(lC) may simply 
delete the LCK. . entry on its 90-minute clean-up rounds. The alarm may go off 
while the user program is in a read(2) or write(2) system call, causing an 
apparent error return. If the user program expects to be around for an hour or 
more, error returns from reads should be checked for (errno=EINTR) , and the 
read possibly reissued. 



Page 2 



10/89 



doconfig(3N) 



doconfig(3N) 



NAME 

doconf ig - execute a configiiration script 
SYNOPSIS 

# include <sac.h>int doconf ig(int fd, char *script, long rf lag) ; 
DESCRIPTION 

doconfig is a Service Access Facility library function that interprets the 
configuration scripts contained in the files /etc/saf/pmteg/_config, 
/etc/saf /_sysconf ig, and /etc/ saf /pmtag/svctag. 

script is the name of the configuration script; fd is a file descriptor that desig- 
nates the stream to which stream manipulation operations are to be applied; rflag 
is a bitmask that indicates the mode in which script is to be interpreted, rflag 
may take two values, NORDN and NOASSIGN, which may be or'd. If rflag is zero, 
all commands in the configuration script are eligible to be interpreted. If rflag has 
the NOASSIGN bit set, the assign command is considered illegal and will generate 
an error return. If rflag has the NORUN bit set, the run and runwait commands 
are considered illegal and will generate error returns. 

The configuration language in which script is written consists of a sequence of 
commands, each of which is interpreted separately. The following reserved key- 
words are defined: assign, push, pop, runwait, and run. The comment charac- 
ter is #; when a # occurs on a line, everything from that point to the end of the 
line is ignored. Blank lines are not significant. No line in a command script may 
exceed 1024 characters. 

assign variable=value 

Used to define environment variables, variable is the name of the 
environment variable and value is the value to be assigned to it. The 
value assigned must be a string constant; no form of parameter substitu- 
tion is available, value may be quoted. The quoting rules are those used 
by the shell for defining environment variables, assign will fail if space 
cannot be allocated for tiie new variable or if any part of the 
specification is invalid. 

push modulell, module!, moduleS, . . .] 

Used to push STREAMS modules onto the stream designated by fd. 
modulel is the name of the first module to be pushed, module! is the 
name of the second module to be pushed, etc. The command will fail if 
any of the named modules cannot be pushed. If a module cannot be 
pushed, the subsequent modules on the same command line will be 
ignored and modules that have already been pushed will be popped. 

pop [module] 

Used to pop STREAMS modules off the designated stream. If pop is 
invoked with no arguments, the top module on the stream is popped. If 
an argument is given, modules will be popped one at a time until the 
named module is at the top of the stream. If the named module is not 
on the designated stream, the stream is left as it was and the command 
fails. If module is the special keyword ALL, then all modules on the 
stream will be popped. Note that only modules above the topmost 
driver are affected. 
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runwait command 

The runwait command runs a command and waits for it to complete. 
command is the pathname of the command to be nm. The command is 
run with /usr/bin/sh -c prepended to it; shell scripts may thus be 
executed from configuration scripts. The runwait command will fail if 
command cannot be found or cannot be executed, or if command exits 
with a non-zero status. 

run command 

The run command is identical to runwait except that it does not wait 
for command to complete, command is the pathname of the command to 
be run. run will not fail unless it is unable to create a child process to 
execute the command. 

Although they are syntactically indistinguishable, some of the commands avail- 
able to run and runwait are interpreter built-in commands. Interpreter built-ins 
are used when it is necessary to alter the state of a process within the context of 
that process. The doconfig interpreter built-in commands are similar to the shell 
special commands and, like these, they do not spawn another process for execu- 
tion. See sh(l). The initial set of built-in commands is: 

cd 

ulimit 
vunask 

DIAGNOSTICS 

doconfig returns 0 if the script was interpreted successfully. If a command in 
the script fails, the interpretation of the script ceases at that point and a positive 
number is returned; this number indicates which line in the script failed. If a sys- 
tem error occurs, a value of -1 is returned. When a script fails, the process 
whose environment was being established should not be started. 

SEE ALSO 

proadmClM), sacadm(lM), sh(l). 
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NAME 

ethers - Ethernet address mapping operations 

SYNOPSIS 

#indude <sys/types.h> 
#include <sys/ socket. h> 
#include <net/if.h> 
#include <netinet/in.h> 
#include <hetinet/if_ether.h> 

char * 

etherjitoa (e> 

struct ether jaddr *e; 

struct ether_addr * 
etherjaton (s) 
char *s; 

ether jntohost (hostname^ e> 
char "^hostname; 
struct ether jaddr *e; 

ether^hostton (hostname , e ) 
char ^hostname; 
struct ether jaddr *e; 

ether_line (1, e, hostname) 
char *1/ 

struct ether_addr *e; 
char ^hostname; 

DESCRIPTION 

These routines are useful for mapping 48 bit Ethernet numbers to their ASCII 
representations or their corresponding host names, and vice versa. 

The function ether_ntoa ( ) converts a 48 bit Ethernet number pointed to by e to 
its standard ASQI representation; it returns a pointer to the ASQI string. The 
representation is of the form x\x\x\x\x\x where :c is a hexadecimal number between 
0 and ff. The fimction ether atonO converts an ASCII string in the standard 
representation back to a 48 bit lEthernet number; the fimction returns NULL if the 
string cannot be scanned successfully. 

the function etherjritohost () maps an Ethernet number (pointed to by e) to its 
associated hostname. The string pointed to by hostname must be long enough to 
hold the hostname and a NULL character. The function returns zero upon success 
and non-zero upon failure. Inversely, the function etherJiosttonO maps a 
hostname string to its corresponding Ethernet number; the function modifies the 
Ethernet number pointed to by e. The function also returns zero upon success 
and non-zero upon failure. The function ether_line() scans a line (pointed to 
by 1) and sets the hostname and the Ethernet number (pointed to by e). The 
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string pointed to by hostname must be long enough to hold the hostname and a 
NULL character. The function returns zero upon success and non-zero upon 
failure. The format of the scanned line is described by ethers(4). 

FILES 

/etc/ethers 

SEE ALSO 

ethers(4) 
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NAME 

gethostent, gethostbyaddrr gethostbyname, sethostent^ endhostent - 
get network host entry 

SYNOPSIS 

♦include <sys /types. h> 
♦include <sys/soc)cet.h> 
♦include <netdb.h> 

struct hostent *gethostent ( ) 

struct hostent *gethostbyaddr (addr , len, type) 
char *addr; 
int len, type; 

struct hostent ^gethostbyname (naxne) 
char *name; 

sethostent (stayopen) 
int stayopen 

endhostent ( ) 

DESCRIPTION 

gethostent ( ), gethostbyaddr ( ), and gethostbyname ( ) each return a pointer 
to an object with the following structure containing the broken-out fields of a line 
in the network host data base, /etc/hosts. In the case of gethostbyaddr ( ) , 
addr is a pointer to the binary format address of length len (not a character 
string). 

stzucthostent { 

char *hjianie; /* official name of host */ 

char **h_aliases; /* alias list */ 

int h__addrtype; /* address type */ 

int h__length; /* length of address */ 

char **h_addr__list; /* list of addresses from name server */ 

}; 

The members of this structure are: 

hjiame Official name of the host. 

hjiliases A zero terminated array of alternate names for the 

host. 

hjiddrtype The type of address being returned; currently 

always af_inet. 

hjength The length, in bytes, of the address. 

hjiddrjist A pointer to a list of network addresses for the 

named host. Host addresses are returned in net- 
work byte order. 

gethostent ( ) reads the next line of the file, opening the file if necessary. 
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sethostent ( ) opens and rewinds the file. If the stayopen flag is non-zero, the 
host data base will not be closed af^er each call to gethostent ( ) (either directly, 
or indirectly through one of the other gethost calls). 

endhostent ( ) closes the file. 

gethostbyname ( ) and gethostbyaddr ( ) sequentially search from the beginning 
of the file until a matching host name or host address is found, or tmtil an EOF is 
encountered. Host addresses are supplied in network order. 

gethostJbyaddr ( ) takes a pointer to an address structure. This structure is 
unique to each type of address. For addres of type af_INET this is in_addr struc- 
ture. See <netinet/in.h>. 

FILES 

/etc/hosts 

SEE ALSO 

hosts(4) 

DIAGNOSTICS 

A NULL pointer is returned on an EOF or error. 

BUGS 

All information is contained in a static area so it must be copied if it is to be 
saved. Only the Internet address format is currently imderstood. 
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NAME 

getnetconf ig - get network configuration database entry 

SYNOPSIS 

♦include <netconfig.h> 

void * 

setnetconfig ( ) 

struct netconf ig * 
getnetconfig (handlep) 
void * handlep 

int 

endnetconfig (handlep) 
void * handlep 

struct netconf ig * 
getnetconf igent (netid) 
char * netid ; 

int 

freenetconf igent (netconf igp) 

struct netconfig * netconf igp ; 

DESCRIPTION 

The five library routines described on this page are part of the UNIX System V 
Network Selection component. They provide application access to the system 
network configuration database, /etc/netconf ig. In addition to the netconfig 
database and the routines for accessing it. Network Selection includes the 
environment variable NETPATH (see environ(5)) and the NETPATH access routines 
described in getnetpath(3N). 

A call to setnetconfig 0 has the effect of "binding" or "rewinding" the 
netconfig database, setnetconfig () must be called before the first call to get- 
netconfig () and may be called at any other time, setnetconfig () need not be 
called before a call to getnetconfigentO. setnetconfig () returns a unique 
handle to be used by getnetconf ig() . 

When first called, getnetconfig () returns a pointer to the current entry in the 
netconfig database, formatted as a struct netconfig. getnetconfig () can 
thus be used to search the entire netconfig file, getnetconfig () returns NULL 
at end of file. 

endnetconfig 0 should be called when processing is complete to release 
resources for reuse. Programmers should be aware, however, that the last call to 
endnetconfig 0 frees all memory allocated by getnetconfig () for the struct 
netconfig data structure, endnetconfig () may not be called before set- 
netconfig (). endnetconfig 0 returns 0 on success and -1 on failure (e.g., if 
setnetconfig 0 was not called previously). 

getnetconf igent (n^fi^f) returns a pointer to the struct netconfig structure 
corresponding to netid. It returns NULL if netid is invalid (i.e., does not name an 
entry in the netconfig database). It returns NULL and sets ermo in case of 
failure (e.g., if setnetconfig () was not called previously). 
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freenetconfigent (nefcon/i^) frees the netconfig structure pointed to by 
netconfigp (previously returned by getinetconfigent ()). 

SEE ALSO 

netconf ig(4), getnetpathON), environ(5) 
Network Programme/s Guide 
System Administrator's Guide 
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NAME 

getnetentr getnetbyaddr, getnetbyname, setnetent, endnetent - get 
network entiy 

SYNOPSIS 

♦include <netdb.h> 

struct netent *getnetent() 

struct netent *getnetbynaxne (name) 
char *naine; 

struct netent *getnetbyaddr(net, type) 
long net; 
int type; 

setnetent (stayppen) 
int stayopen; 

endnetent ( ) 

DESCRIPTION 

getnetent ( ), getnetbynaxne( ), and get:netbyaddr ( ) each return a pointer to 
an object with the following structure containing the broken-out fields of a line in 
the network data base, /etc/networks. 

struct netent { 

char *njiame; 

char **n_jaliases; 

int n_addrtype; 

long njiet; 

}; 

The members of this structure are: 

njiame The official name of the network. 

njiliases A zero terminated list of alternate names for the network. 

njtddrtype The type of the network number returned; currently only 
AF_INET. 

njiel The network number. Network numbers are returned in 

machine byte order. 

getnetent ( ) reads the next line of the file, opening the file if necessary. 

setnetent ( ) opens and rewinds the file. If the stayopen flag is non-zero, the net 
data base will not be closed after each call to getnetent ( ) (either directly, or 
indirectly through one of the other getnet calls). 

endnetent ( ) closes the file. 

getnetJDynaitiB ( ) and getnetJDyaddr ( ) sequentially search from the beginning 
of the file until a matching net name or net address and type is found, or imtil 
EOF is encountered. Network numbers are supplied in host order. 



/* official name of net */ 
/* alias list */ 
/* net nuntoer type */ 
/* net number */ 
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FILES 

/etc/networks 

SEE ALSO 

neti#orks(4) 

DIAGNOSTICS 

A NULL pointer is returned on EOF or error. 

BUGS 

All information is contained in a static area so it must be copied if it is to be 
saved. 

Only Internet network numbers are currently understood. 
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NAME 

getnetpath - get /etc/netconfig entry corresponding to NETPATH component 

SYNOPSIS 

♦include <netconfig.h> 

void * 
detnetpathO 

struct netconf ig * 
getnetpath (handlep) ; 
void * handlep; 

int 

endnetpath (handlep) ; 
void * handlep; 

DESCRIPTION 

The three routines described on this page are part of the UNIX System V Network 
Selection component. They provide application access to the system network 
configuration database, /etc/netconfig, as it is "filtered" by the NETPATH 
environment variable (see environ(5)). Network Selection also includes routines 
that access the network configuration database directly (see getnetconf ig(3N)). 

A call to setnetpathO "binds" or "rewinds" NETPATH. setnetpathO must be 
called before the first call to getnetpath () and may be called at any other time. 
It returns a handle that is used by get:netpath. setnetpathO will fail if the 
netconf ig database is not present. If NETPATH is unset, setnetpatJi ( ) returns 
the number of "visible" networks in the netconf ig file. The set of visible net- 
works constitutes a default NETPATH. 

When first called, getnetpath () returns a pointer to the netconf ig database 
entry corresponding to the first valid NETPATH component. The netconf ig entry 
is formatted as a struct netconfig. On each subsequent call, getnetpath 
returns a pointer to the netconfig entry that corresponds to the next valid NET- 
PATH component, getnetpath () can thus be used to search the netconfig data- 
base for all networks included in the NETPATH variable. When NETPATH has been 
exhausted, getnetpath () returns NULL. 

getnetpath 0 silently ignores invalid NETPATH components. A NETPATH com- 
ponent is invalid if there is no corresponding entry in the netconfig database. 

If the NETPATH variable is unset, getnetpath () behaves as 2/ NETPATH were set to 
the sequence of "default" or "visible" networks in the netconfig database, in 
the order in which they are listed. 

endnetpath 0 may be called to "unbind" NETPATH when processing is complete, 
releasing resources for reuse. Programmer's should be aware, however, that end- 
netpath () frees all memory allocated by setnetpatJi 0 . endnetpath () returns 
0 on success and -1 on failure (e.g., if setnetpathO was not called previously). 

SEE ALSO 

netconf ig(4), getnetconf ig(3N), environ(5) 
Network Programmer's Guide 
System Administrator's Guide 
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NAME 

getpeername - get name of connected peer 

SYNOPSIS 

int getpeername (s, name, namelen) 
int s; 

struct sockaddr *name; 
int ^namelen; 

DESCRIPTION 

getpeername( ) returns the name of the peer connected to socket s. The int 
pointed to by the mmelen parameter should be initialized to indicate the amount 
of space pointed to by name. On return it contains the actual size of the name 
retumed(in bytes). The name is truncated if the buffer provided is too small. 

RETURN VALUE 

0 is returned if the call succeeds, -1 if it fails. 

ERRORS 

The call succeeds unless: 

EBADF The argument s is not a valid descriptor. 

ENOTSOCK The argument s is a file, not a socket. 

ENOTCONN The socket is not connected. 

ENOMEM There was insufficient user memory for the operation to 

complete. 

ENOSR There were insufficient STREAMS resources available for the 

operation to complete. 

SEE ALSO 

accept(3N), bind(3N), getsockname(3N), socket(3N) 
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NAME 

getprotoent, getprotobynvinber, getprotdbyname, setprotoent^ endpro- 
toent - get protocol entry 

SYNOPSIS 

tinclude <netdb.h> 

struct protoent *getprotoent ( ) 

struct protoent *getprot6bynaxne (name) 
char *na2ne; 

struct protoent ^getprotdbynisrber (proto) 
int proto; 

setprotoent (stayopen) 
int stayopen; 

endprotoent ( ) 

DESCRIPTION 

getprotoent ( ) , getprotobynaxneC ), and getprotobynuntoer ( ) each return a 
pointer to an object with the following structure containing the broken-out fields 
of a line in the network protocol data base, /etc/protocols. 

struct protoent { 

char *p_naine; /* official naine of protocol */ 

char **p_aliases; /* alias list */ 

int pjproto; /* protocol nuitiber */ 

}; 

The members of this structure are: 

pjiame The official name of the protocol. 

pjiliases A zero terminated list of alternate names for the 

protocol. 

pjproto The protocol number. 

getprotoent ( ) reads the next line of the file, opening the file if necessary. 

setprotoent ( ) opens and rewinds the file. If the stayopen flag is non-zero, the 
net data base will not be closed after each call to getprotoent ( ) (either directly, 
or indirectly through one of the other getproto calls). 

endprotoent ( ) closes the file. 

getprotobynaitie ( ) and getprotobynuirber ( ) sequentially search from the 
beginning of the file until a matching protocol name or protocol number is foimd, 
or until an EOF is encoimtered. 

FILES 

/etc/protocols 

SEE ALSO 

protocols(4) 
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DIAGNOSTICS 

A NULL pointer is returned on an EOF or error. 

All information is contained in a static area so it must be copied if it is to be 
saved. Only the Internet protocols are currently understood. 
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NAME 

getservent, getservbyport, getsein^yname^ setservent, endservent ~ 
get service entry 

SYNOPSIS 

finclude <netdb.h> 

struct servent *getservent ( ) 

struct servent *getservbyna2ne(naine^ ^roto) 
char *naine, *proto; 

struct servent *getser^*yport(portr proto) 
int port; 
char *proto; 

setservent (stayqpen) 
int stayqpen; 

endservent ( ) 

DESCRIPTION 

getservent ( ), getservbynameO, and getservbyportO each return a pointer to an 
object with the following structure containing the broken-out fields of a line in 
the network services data base, /etc/ services. 

struct servent { 

char *s_name; 

char **s_jaliases; 

int s_port; 

char *sjproto; 

}; 

The members of this structure are: 

sjiame The official name of the service. 

sjiliases A zero terminated list of alternate names for the ser- 

vice. 

sjyort The port number at which the service resides. Port 

numbers are returned in network short byte order. 

s_proto The name of the protocol to use when contacting the 

service. 

getservent ( ) reads the next line of the file, opening the file if necessary. 

setservent ( ) opens and rewinds the file. If the stayopen flag is non-zero, the 
net data base will not be closed after each call to getservent ( ) (either directly, 
or indirectly through one of the other getserv calls). 

endservent ( ) closes the file. 

getservbyname ( ) and getservbyport ( ) sequentially search from the beginning 
of the file until a matching protocol name or port number is found, or until EOF 
is encoimtered. If a protocol name is also supplied (non-NULL), searches must 
also match the protocol. 



/* official naine of service */ 
/* alias list */ 
/* port service resides at */ 
/* protocol to use */ 
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FILES 

/etc/services 

SEE ALSO 

getprotoentON), services(4) 

DIAGNOSTICS 

A NULL pointer is returned on EOF or error. 

All information is contained in a static area so it must be copied if it is to be 
saved. Expecting port numbers to fit in a 32 bit quantity is probably naive. 
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NAME 

getsocknaine - get socket name 

SYNOPSIS 

getscxsknameCs, naxner namelen) 
int s; 

struct sockaddr *naine; 
int *naxnelen; 

DESCRIPTION 

getsocknameO returns the current name for socket s. The namelen parameter 
should be initialized to indicate the amount of space pointed to by name. On 
return it contains the actual size of the name retumed(in bytes). 

RETURN VALUE 

0 is returned if the call succeeds; -1 if it fails. 

ERRORS 

The call succeeds unless: 

EBADF The argument s is not a valid descriptor. 

ENOTSOCK The argimient s is a file, not a socket. 

ENOMEM There was insufficient user memory for the operation to 

complete. 

ENOSR There were insufficient STREAMS resources available for the 

operation to complete. 

SEE ALSO 

bindON), getpeernameON), socket(3N) 
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NAME 

getsockopt, setsockopt - get and set options on sockets 

SYNOPSIS 

♦include <sys/types . h> 
♦include <sys/ socket. h> 

int getsockopt (s, levels optname, optval, c^tlen) 
int s, level, ppt:naxne; 
char *qptval; 
int *pptlen; 

int setsockopt (s, level, optname, cptval, qptlen) 
int s, level, optname; 
char *optval; 
int cptlen; 

DESCRIPTION 

getsockoptO and setsockoptO manipulate options associated with a socket. 
Options may exist at multiple protocol levels; they are always present at the 
uppermost socket level. 

When manipulating socket options, the level at which the option resides and the 
name of the option must be specified. To manipulate options at the socket level, 
level is specified as S0LJ50CKET. To manipulate options at any other level, level is 
the protocol number of the protocol that controls the option. For example, to 
indicate that an option is to be interpreted by the TCP protocol, level is set to the 
TCP protocol number [see getprotoent(3N)]. 

The parameters optval and optlen are used to access option values for set-^ 
sockoptC ). For getsockopt( ), they identify a buffer in which the value(s) for the 
requested option(s) are to be returned. For getsockoptO , optlen is a value-result 
parameter, initially containing the size of the buffer pointed to by optval, and 
modified on return to indicate the actual size of the value returned. If no option 
value is to be supplied or returned, a 0 optval may be supplied. 

optname and any specified options are passed iminterpreted to the appropriate 
protocol module for interpretation. The include file 
/usr/include/sys/socket . h contains definitions for the socket-level options 
described below. Options at other protocol levels vary in format and name. 

Mpst socket-level options take an int for of^vcd. For setsockoptO, the optval 
parameter should be non-zero to enable a boolean option, or zero if the option is 
to be disabled. SO_LINGER uses a struct linger parameter that specifies the 
desired state of the option and the linger interval (see below), struct linger is 
defined in /usr/include/sys/ socket. h. 

The following options are recognized at the socket level. Except as noted, each 
may be examined with getsockoptO and set with setsockoptO. 

SpJ)EBUG toggle recording of debugging information 

SO_REUSEADDR toggle local address reuse 
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SqjCEEPALIVE 

SOJDONTROUTE 

SO_LINGER 

SO_BROADCAST 

SOJX)BINLINE 

SO_SNDBUF 

SO_RCVBUF 

SOJTYPE 

SO moR 



toggle keep connections alive 

toggle routing bypass for outgoing messages 

linger on close if data is present 

toggle permission to transmit broadcast messages 

toggle reception of out-of-band data in band 

set buffer size for output 

set buffer size for input 

get the type of the socket(get only) 

get and clear error on the socket(get only) 



SO^DEBUG enables debugging in the underlying protocol modules. SO_REUSEAPDR 
indicates that the rules used in validating addresses supplied in a bind(3N) call 
should allow reuse of local addresses. SO_KEEPALIVE enables the periodic 
transmission of messages on a connected socket. If the connected party fails to 
respond to these messages, the connection is considered broken and processes 
using the socket are notified using a SIGPIPE signal. SOJDONTROUTE indicates 
that outgoing messages should bypass the standard routing facilities. Instead, 
messages are directed to the appropriate network interface according to the net- 
work portion of the destination address. 

SOJLINGER controls the action taken when unsent messages are queued on a 
socket and a ciose(2) is performed. If the socket promises reliable delivery of 
data and SOJdlNGER is set, the system will block the process on the closeO 
attempt until it is able to transmit the data or imtil it decides it is unable to 
deliver the information (a timeout period, termed the linger interval, is specified 
in the setsockoptO call when SOJuINGER is requested). If SOJLINGER is dis- 
abled and a clos^ ( ) is issued, the system will process the close () in a manner 
that allows the process to continue as quickly as possible. 

The option SOJBROADCAST requests permission to send broadcast datagrams on 
the socket. With protocols that support out-of-band data, the SOJDOBINLINE 
option requests that out-of-band data be placed in the normal data input queue ^s 
received; it will then be accessible with recv() or readO calls without the 
MSGJDOB flag. SO_SNDBUF and Sp_RCVBUF are options that adjust the normal 
buffer sizes allocated for output and input buffers, respectively. The buffer size 
may be increased for high-volume connections or may be decreased to limit the 
possible backlog of incoming data. The system places an absolute limit on these 
values. Finally, SOJTYPE and SO_ERROR are options used only with g^t- 
sockopt( ). SOJTYPE returns the type of the socket (for example, SOCKJSTREAM) . 
It is useful for servers that inherit sockets on startup. SO_ERROR returns any 
pending error on the socket and clears the error status. It may be used to check 
for asynchronous errors on connected datagram sockets or for other asynchro- 
nous errors. 

RETURN VALUE 

A 0 is returned if the call succeeds, -1 if it fails. 

ERRORS 

The call succeeds unless: 



Page 2 



10/89 



getsockopt(3N) 



get80ckopt(3N} 



EBADF 
ENOTSOCK 
ENOPROTOOPT 
ENOMEM 



ENOSR 
SEE ALSO 



The argument s is not a valid descriptor. 

The argument s is a file, not a socket. 

The option is unknown at the level indicated. 

There was insufficient user memory available for the opera- 
tion to complete. 

There were insufficient STREAMS resources available for the 
operation to complete. 



ioctl(2X socketON), getprotoent(3N). 
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NAME 

inet: inet_addr, inet_network, inet_inakeacUir, inet_lnaof, inetjietof, 
inet_ntoa ~ Internet address manipulation 

SYNOPSIS 

♦include <sys /types . h> 
♦include <sys/socket .h> 
♦include <netinet/in.h> 
♦include <arpa/inet.h> 

unsigned long 
inet jaddr (cp) 
cliar *cp; 

inet_network (cp) 
char *cp; 

struct in_addr 
inet^makeaddr (net, Ina) 
int net, Ina; 

inet_lnaof (in) 
struct in_addr in; 

inet_netof (in) 
struct in_addr in; 

char * 

inetjitoa(in) 
struct injaddr in; 

DESCRIPTION 

The routines inet_addr ( ) and inet_network ( ) each interpret character strings 
representing numbers expressed in the Internet standard notation, returning 
numbers suitable for use as Internet addresses and Internet network numbers, 
respectively. The routine inet jmakeaddr ( ) takes an Internet network number 
and a local network address and constructs an Internet address from it. The rou- 
tines inetjietof ( ) and inet_lnaof ( ) break apart Internet host addresses, 
returning the network number and local network address part, respectively. 

The routine inet__ntoa ( ) returns a pointer to a string in the base 256 notation 
d.d.d.d described below. 

All Internet addresses are returned in network order (bytes ordered from left to 
right). All network numbers and local address parts are returned as machine for- 
mat integer values. 

INTERNET ADDRESSES 

Values specified using the notation take one of the following forms: 

a.b.c.d 
a.b.c 
a.b 
a 
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When four parts are specified, each is interpreted as a byte of data and assigned, 
from left to right, to the four bytes of an Internet address. 

When a three part address is specified, the last part is interpreted as a 16-bit 
quantity and placed in the right most two bytes of the network address. This 
makes the three part address format convenient for specifying Class B network 
addresses as 128.net.host. 

When a two part address is supplied, the last part is interpreted as a 24-bit quan- 
tity and placed in the right most three bytes of the network address. This makes 
the two part address format convenient for specifying Class A network addresses 
as net.host. 

When only one part is given, the value is stored directly in the network address 
without any byte rearrangement. 

All ntimbers supplied as parts in a notation may be decimal, octal, or hexade- 
cimal, as specified in the C language (that is, a leading Ox or OX implies hexade- 
cimal; otherwise, a leading 0 implies octal; otherwise, the number is interpreted 
as decimal). 

SEE ALSO 

gethostentON), getnetentON), hosts(4), networks(4) 
DIAGNOSTICS 

The value -1 is returned by inet_addr ( ) and inet_network ( ) for malformed 
requests. 

BUGS 

The problem of host byte ordering versus network byte ordering is confusing. A 
simple way to specify Class C network addresses in a manner similar to that for 
Class B and Class A is needed. 

The return value from inet_ntoa<) points to static information which is 
overwritten in each call. 
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NAME 



listen " listen for connections on a socket 

SYNOPSIS 

listen (s, backlog) 
int s, backlog; 

DESCRiPTION 

To accept connections, a socket is first created with socket(2), a backlog for 
incoming connections is specified with listen ( ) and then the connections are 
accepted with accept(2). The listen () call applies only to sockets of type 
SOCKJSTREAM or SOCKJSEQPACKET. 

The backlog parameter defines the maximum length the queue of pending connec- 
tions may grow to. If a connection request arrives with the queue full, the client 
will receive an error with an indication of ECX)NNREFaSED. 

RETURN VALUE 

A 0 return value indicates success; -1 indicates an error. 



ERRORS 



The call fails if: 



EOPNOTSUPP 



EBADF 



ENOTSOCK 



The argument s is not a valid descriptor. 
The argument s is not a socket. 

The socket is not of a type that supports the operation 
listen. 



NOTES 



There is currently no backlog limit. 
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NAME 

netdir_getbynaine, netdir_getbyaddir, netdir_free, netdirjnergeaddr, 
taddr2uaddr, uaddr2taddr, netdirj>error, netdir_sperror - generic tran- 
sport name-to-address translation 

SYNOPSIS 

tinclude <netdir.h> 

int 

netdirjgetbyname (config, service ^ addrs) 
stmct netconfig *conf ig; 
struct ndjiostserv ^service; 
struct nd_addrlist **addrs; 

int 

netdir jgetJ^yaddr (conf ig, service, netaddr) 
struct netconfig *config; 
struct ndjtiostservlist **service; 
struct netbuf *netaddr; 

void 

netdir_f ree (pt r , ident ) 
void *ptr; 
int ident; 

int 

netdir_mergeaddr (conf ig, mrgjuaddr, sjuaddr, cjuaddr) 
struct netconfig *config; 
char **inrgjuaddr, *sjuaddrr *cjuaddr; 

char * 

taddr2uaddr(config, addr) 

struct netconfig *config; 
struct netbuf *addr; 

struct netbuf * 
uaddr2taddr(config, uaddr) 

struct netconfig *config; 

char *uaddr; 

int 

netdirjpptions (netconfig, qption, fd, pointer_to_args) 
struct netconfig *netconfig; 
int qption; 
int fd; 

char *pointjto_args; 

void 

netdir_perror (s) 
char *s; 

char * 

netdir__sperror ( ) 
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DESCRIPTION 

These routines provide a generic interface for name-to-address mapping that will 
work with a all transport protocols. This interface provides a generic way for pro- 
grams to convert transport specific addresses into common structures and back 
again. 

The netdir_getbyname ( ) routine maps the machine name and service name in 
the nd_hostserv structure to a collection of addresses of the type understood by 
the transport identified in the netconf ig structure. This routine returns all 
addresses that are valid for that transport in the nd__addrlist structure. The 
ndjiostserv and nd_addrlist structures have the following elements. The 
netconf ig structure is described on the netconf ig(4) manual page. 

stanact ndjaddrlist 
int njcnt 

struct netJ:>uf *njaddrs; 

struct nd_hostserv 
char *h_host; 
char *h__serv; 

netdirjgetbyname ( ) accepts some special-case host names. These host names 
are hints to the underlying mapping routines that define the intent of the request. 
This information is required for some transport provider developers to provide 
the correct information back to the caller. The host names are defined in 
/usr/include/netdir.h. The currently defined host names are: 

HOST^SELF Represents the address to which local programs will bind their end- 
points. H0STJ5ELF differs from the host name provided by 
gethostnameO), which represents the address to which remote pro- 
grams will bind their endpoints. 

HOST_ANY Represents any host accessible by this transport provider. HOSTJMJY 
allows applications to specify a required service without specifying a 
particular host name. 

HOST_BROADCAST 

Represents the address for all hosts accessible by this transport pro- 
vider. Network requests to this address will be received by all 
machines. 

All fields of the ndjiostserv structure must be initialized. 

To find all available transports, call the netdirjgetbyname ( ) routine with each 
struct netconf ig structure returned by the getnetpathON) call. 

The netdirjgetJDyaddr ( ) routine maps addresses to service names. This rou- 
tine returns a list of host and service pairs that would yield this address. If more 
than one tuple of host and service name is returned then the first tuple contains 
the preferred host and service names. 

struct nd_hostservlist 
int *h_jcnt; 

struct hostserv *h hostservs; 
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The netdir_f ree ( ) structure is used to free the structures allocated by the name 
to address translation routines. 

The netdir_inergeaddr( ) routine is used by a network service to return an 
optimized network addresses to a client. This routine takes the universal address 
of the endpoint that the service has bound to, which is pointed to by the sjiaddr 
parameter, and the address of the endpoint that a request came in on, which is 
pointed to by the cjiaddr paramter, to create an optimized address for communi- 
cation with the service. The service address should be an address returned by the 
netdir jgetbyname ( ) call, specified with the special host name HOSTjSEif. 

The taddr2uaddr ( ) and uaddr2taddr ( ) routines support translation between 
universal addresses and TLI type netbufs. The take and return character string 
pointers. The taddr2uaddr ( ) routine returns a pointer to a string that contains 
the universal address and returns NULL if the conversion is not possible. This is 
not a fatal condition as some transports may not suppose a universal address 
form. 

option, fd, and pointer Jojirgs are passed to the netdirjoptions routine for the 
transport specified in netconf igp. There are four values for option: 

ND_SET_BROADCAST 
ND_SET_RESERVEDPORT 
NDjCHECK_RESERVEDPORT 
NDJffiRGEADDR 

If a transport provider does not support an option, netdir_options returns -1 
and sets jiderror to ND_NOCTRL. 

The specific actions of each option follow. 

NDJSETJBROADCAST Sets the transport provider up to allow broadcast, if the 
transport supports broadcast, fd is a file descriptor into the 
transport (i.e., the result of a tjopen of /dev/udp). 
pointer Jo jirgs is not used. If this completes, broadcast 
operations may be performed on file descriptor fd. 

NDjSET_RESERVEDPORT 

Allows the application to bind to a reserved port, if that 
concept exists for the transport provider, fd is a file 
descriptor into the transport (it must not be bound to an 
address). If pointer Jo _args is NULL, fd will be bound to a 
reserved port. If pointer Jojirgs is a pointer to a netJDuf 
structure, an attempt will be made to bind to a reserved 
port on the specified address. 

ND_CHECKJRESERVEDPORT 

Used to verify that an address corresponds to a reserved 
port, if that concept exists for the transport provider, fd is 
not used, pointer Jojirgs is a pointer to a netJDuf structure 
that contains an address. This option returns 0 only if the 
address specified in pointer Jojirgs is reserved. 
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ND^MER^ADDR Used to take a 'local address" (like the 0.0.0.0 address 

that TCP uses) and return a "real address" that client 
machines can connect to. fd is not used, pointer Jo jifgs is a 
pointer to a struct ndjnnergearg/ which has the following 
form: 

struct ndjnergearg { 

diar *sjuaddr; /* server's universal address */ 
diar *cjaaddr; /* client's xmiversal address */ 
diar *mjaaddr; /* the result */ 

> 

s_uaddr is something like 0 . 0 . 0 . 0 . 1 . 12, and, if the call is 
successful, mjuaddr will be set to something like 
192.11.109.89.1.12. For most transports, mjuaddi: is 
exactly what s_uaddr is. 

The netdirjperror 0 routine prints an error message on the standard output 
stating why one of the name-to-address mapping routines failed. The error mes- 
sage is preceded by the string given as an argument. 

The netdir_sperror() routine returns a string containing an error message stat- 
ing why one of the name-to-address mapping routines failed. 

SEE ALSO 

getnetpathON) 
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NAME 

nlsgetcall - get client's data passed via the listener 

SYNOPSIS 

tinclude <sys/tiuser . h> 

struct tjcall *nlsgetcall (int fd); 

DESCRIPTION 

nlsgetcall allows server processes started by the listener process to access the 
client's t_call structure, that is, the sndcall argument of t_connect(3N). 

The tjcall structure returned by nlsgetcall can be released using t_f ree(3N). 

nlsgetcall returns the address of an allocated t_jcall structure or NULL if a 
tjcall structure cannot be allocated. If the t_alloc succeeds, undefined 
environment variables are indicated by a negative Un field in the appropriate net- 
bu£ structure. A len field of zero in the netbuf structure is valid and means that 
the original buffer in the listener's tjcall structure was NULL. 

WARNING 

The Un field in the netbuf structure is defined as being imsigned. In order to 
check for error returns, it should first be cast to an int. 

The listener process limits the amoimt of user data (udata) and options data (opt) 
to 128 bytes each. Address data addr is limited to 64 bytes. If the original data 
was longer, no indication of overflow is given. 

DIAGNOSTICS 

A NULL pointer is returned if a t_call structure cannot be allocated by t_alloc. 
t_ermd can be inspected for further error information. Undefined environment 
variables are indicated by a negative length field (len) in the appropriate netbuf 
structure. 

FILES 

/usr/lib/libnsl_s . a 
/usr/lib/libslan . a 
/usr/lib/libnls . a 

SEE ALSO 

nlsadmin(l), getenv(3), t_connect(3N), t_alloc(3N)/ t_free(3N), t_error(3N). 

NOTES 

Server processes must call t_sync(3ND before calling this routine. 
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NAME 

nlsprovider - get name of transport provider 

SYNOPSIS 

char *nlsprovider() ; 

DESCRIPTION 

nlsprovider returns a pointer to a null terminated character string which con- 
tains the name of the transport provider as placed in the environment by the 
listener process. If the variable is not defined in the environment, a NULL pointer 
is returned. 

The environment variable is only available to server processes started by the 
listener process. 

SEE ALSO 

nlsadmin(lM). 

DIAGNOSTICS 

If the variable is not defined in the environment, a NULL pointer is returned. 

FILES 

/usr/lib/libslan.a (7300) 
/usr/lib/libnls.a (3B2 Computer) 
/usr/ljLb/libnsl_s . a 
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NAME 

nlsrequest - format and send listener service request message 

SYNOPSIS 

♦include <listen.h> 

int nlsrequest (int fd^ char ♦servicejcode) ; 

extern int _nlslog, tjerrno; 
extern char *jnlsnnsg; 

DESCRIPTION 

Given a virtual circuit to a listener process ifd) and a service code of a server pro- 
cess, nlsrequest formats and sends a service request message to the remote listener 
process requesting that it start the given service, nlsrequest waits for the remote 
listener process to return a service request response message, which is made available 
to the caller in the static, null terminated data buffer pointed to by _nlsnnsg. 
The service request response message includes a success or failure code and a text 
message. The entire message is printable. 

SEE ALSO 

nlsadmin(l), t_error(3). 

FILES 

/usr/lib/libnls.a 
/usr/lib/libslan . a 
/usr/lib/libnsl_s . a 

DIAGNOSTICS 

The success or failure code is the integer return code from nlsrequest. Zero 
indicates success, other negative values indicate nlsrequest failures as follows: 

-1 : Error encountered by nlsrequest, see t_errno. 

Postive values are error return codes from the listener process. Mnemonics for 
these codes are defined in <listen.h>. 

2 : Request message not interpretable. 

3 : Request service code unknown. 

4 : Service code known, but currently disabled. 

If non-null, _nlsnnsg contains a pointer to a static, null terminated character 
buffer containing the service request response message. Note that both _nlsr3nsg 
and the data buffer are overwritten by each call to nlsrequest. 

If _nlslog is non-zero, nlsrequest prints error messages on stderr. Initially, 
_nlslog is zero. 

WARNING 

nlsrequest cannot always be certain that the remote server process has been 
successfully started. In this case, nlsrequest returns with no indication of an 
error and the caller will receive notification of a disconnect event via a TJDOOK 
error before or during the first t_snd or t_rcv call. 
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NAME 

publickey: getpublickey, getsecretkey - retrieve public or secret key 

SYNOPSIS 

♦include <rpc/rpc.h> 
iinclude <rpc/key_prot.h> 

9etpii:>lickey (const char netname [MAXNETNAMBLEN] ^ 
char publickey[HEXiCEYBYTES] ) ; 

getsecretkey (const char netnaxne [MAXNETNAMELEN] , 

char 8ecretkey[HEXKEYBYTES] , const char *passwd); 

DESCRIPTION 

getpublickey and getsecretkey get public and secret keys for netname from 
the publickey(4) database. 

getsecretkey has an extra argument, passwd, used to decr5^t the encrypted 
secret key stored in the database. 

Both routines return 1 if they are successful in finding the key, 0 otherwise. The 
keys are returned as NULL-terminated, hexadecimal strings. If the password 
supplied to getsecretkey fails to decrypt the secret key, the routine will return 
1 but the secreikey argument will be a NIJLL string. 

SEE ALSO 

publickey(4). 
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NAME 

recv, recvf ronir recvmsg - receive a message from a socket 

SYNOPSIS 

♦include <sys/types . h> 
♦include <sys/soclcet.h> 

int recvCs, buf, len, flags) 

int s; 

char ♦buf ; 

int len, flags; 

int recvfrcni(s, buf, len, flags^ from, fromlen) 

int s; 

char *buf ; 

int len, flags; 

struct sockaddr *from; 

int * fromlen; 

int recvmsg (s^ msg^ flags) 
int s; 

struct msghdr *msg; 
int flags; 

DESCRIPTION 

s is a socket created with socket (3N). recvO, recvfromO, and recvmsg () are 
used to receive messages from another socket. recvO may be used only on a 
connected socket (see connectON)), while recvfromO and recvmsg () may be 
used to receive data on a socket whether it is in a connected state or not. 

If from is not a NULL pointer, the source address of the message is filled in. from- 
len is a value-result parameter, initialized to the size of the biiffer associated with 
from, and modified on return to indicate the actual size of the address stored 
there. The length of the message is returned. If a message is too long to fit in 
the supplied buffer, excess bytes may be discarded depending on the type of 
socket the message is received from (see socketON)). 

If no messages are available at the socket, the receive call waits for a message to 
arrive, unless the socket is nonblocking (see fcntl(2)) in which case -1 is 
returned with the external variable errno set to EWOULDBLOCK. 

The select 0 call may be used to determine when more data arrives. 

The flags parameter is formed by ORing one or more of the following: 

MSGJOOB Read any out-of-band data present on the socket rather than the 

regular in-band data. 

MSGJPEEK Peek at the data present on the socket; the data is returned, but 

not consumed, so that a subsequent receive operation will see 
the same data. 

The recvmsg 0 call uses a msghdr structure to minimize the ntmiber of directly 
supplied parameters. This structure is defined in /usr/include/sys/socket . h 
and includes the following members: 
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caddrjb msgjiane; optional address */ 

int insgjiainelen; h size of address 

struct iovec *insg_iov; h scatter/gather array ^1 

int msg^iovlen; # elements in msg^iov */ 

caddrjb msgjaccric^ts; /* access ri^ts sent/received */ 

int msgjaccrightslen; 

Here insg_name and msg_nainelen specify the destination address if the scxket is 
unconnected; xnsg^name may be given as a NULL pointer if no names are desired 
or required. The xnsg_iov and msg_iovlen describe the scatter-gather locations, 
as described in read(2). A buffer to receive any access rights sent along with the 
message is specified in xnsg_accrights, which has length msgjaccrightslen. 

RETURN VALUE 

These calls return the number of bytes received, or -1 if an error occurred. 

ERRORS 

The calls fail if: 



EBADF 

ENOTSOCK 

EINTR 

EWOOLDBLOCK 

ENOMEM 

ENOSR 

SEE ALSO 

connectON), 
socketON). 



s is an invalid descriptor. 

s is a descriptor for a file, not a socket. 

The operation was interrupted by delivery of a signal 
before any data was available to be received. 

The socket is marked non-blocking and the requested 
operation would block. 

There was insufficient user memory available for the opera- 
tion to complete. 

There were insufficient STREAMS resouces available for the 
operation to complete. 

fcntl(2), getsockoptON), ioctl(2), read(2), send(3N), 
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NAME 

resolver, res_irikquery, res_sencJ, res_init, dnjcx>n|>, dnjeaqpand - resolver 
routines 

SYNOPSIS 

♦include <sys/types.h> 
♦include <netinet/in . h> 
tinclude <arpa/naine8er.h> 
finclude <zesolv.h> 

res_mkquery(pp, dnaxne, class, type, data, datalen, newrr, bu£, buflen) 

int op; 

char *dnaxne; 

int class, type; 

char *data; 

int datalen; 

struct rrec *newrr; 

char *buf ; 

int buflen; 

res_send (xnsg, xnsglen, answer, anslen) 
char *insg; 
int msglen; 
char ^answer; 
int anslen; 

res_init 

dnjccmp (exp_dn, conpjdn, length, diptrs, lastdi^tr) 
char *exp_dn, *ccnpjdn; 
int length; 

char **dnptrs, **lastdr^tr; 

dn_expand(insg, msglen, compjdn, exp_dn, length) 
char *insg, *conpjdn, e:qp_dn; 
int msglen, length; 

DESCRIPTION 

These routines are used for making, sending and interpreting packets to Internet 
domain name servers. Global information that is used by the resolver routines is 
kept in the variable jres. Most of the values have reasonable defaults and can 
be ignored. Options are a simple bit mask and are OR'ed in to enable. Options 
stored in jres. options are defined in /usr/include/resolv.h and are as fol- 
lows. 

RES_INIT True if the initial name server address and default domain 

name are initialized (that is, res_init has been called). 

RESJDEBUG Print debugging messages. 

R£S_AAOMLY Accept authoritative answers only. res_send will continue 

until it finds an authoritative answer or finds an error. 
Currently this is not implemented. 
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RES USEVC 



Use TCP connections for queries instead of UDP. 



B£S STAYOPEN 



Used with BESjaSEVC to keep the TCP connection open 
between queries. This is useful only in programs that regu- 
larly do many queries. UDP should be the normal mode 
used. 



RES IGNTC 



Unused currently (ignore tnmcation errors, that is, do not 
retry with TCP). 



RES RECURSE 



Set the recursion desired bit in queries. This is the default, 
resjsend does not do iterative queries and expects the 
name server to handle recursion. 



RES DEFNAMES 



Append the default domain name to single label queries. 
This is the default. 



res_init reads the initialization file to get the default domain name and the 
Internet address of the initial hosts nmning the name server. If this line does not 
exist, the host running the resolver is tried, resjnkquery makes a standard 
query message and places it in buf, res_inkqueiY will return the size of the 
query or -1 if the query is larger than buflen. op is usually QUERY but can be any 
of the query types defined in /usr/include/arpa/nameser.h. dname is the 
domain name. If dname consists of a single label and the RESJDEFNAMES flag is 
enabled (the default), dname will be appended with the current domain name. 
The current domain name is defined in a system file and can be overridden by 
the environment variable LOCALDOMAIN. newrr is currently unused but is 
intended for making update messages. 

resjsend sends a query to name servers and returns an answer. It will call 
res_init if RES_INIT is not set, send the query to the local name server, and 
handle timeouts and retries. The length of the message is returned or -1 if there 
were errors. 

dnje3q>and expands the compressed domain name comp_dn to a full domain 
name. Expanded names are converted to upper case, msg is a pointer to the 
beginning of the message, exp_dn is a pointer to a buffer of size length for the 
result. The size of compressed name is returned or -1 if there was an error. 

dn_coinnp compresses the domain name exp_dn and stores it in comp_dn. The size 
of the compressed name is returned or -1 if there were errors, length is the size 
of the array pointed to by comp_dn. dnptrs is a list of pointers to previously 
compressed names in the current message. The first pointer points to to the 
beginning of the message and the list ends with NULL, lastdnptr is a pointer to the 
end of the array pointed to dnptrs, A side effect is to update the list of pointers 
for labels inserted into the message by dn_conp as the name is compressed. If 
dnptr is NULL, do not try to compress names. If lastdnptr is NULL, do not update 
the list. 

FILES 

/usr/include/arpa/nameserv . h 
/usr/include/netinet/in . h 
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/usr/incliide/resolv . h 
/usr/include/sys/types .h 
/etc/resolv . conf 
/usr/lib/libresolv . a 

SEE ALSO 

nameddM), resolv.conf(4). 

NOTES 

/usr/lib/libresolv. a is necessary for compiling programs. 
Programs must be loaded with the option -Iresolv. 
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NAME 

rexec - return stream to a remote command 
SYNOPSIS 

rem » rexec(aho8tr inport, user, passwd, cmcL, £d2p}; 

char **ahost; 

u_short inport; 

char *user, *pas8wd, *cad; 

int *fd2p; 

DESCRIPTION 

rexec ( ) looks up the host *ahost using gethostbyname [see gethostentON)], 
returning -1 if the host does not exist. Otherwise *ahost is set to the standard 
name of the host. If a username and password are both specified, then these are 
used to authenticate to the foreign host; otherwise the environment and then the 
user's .netrc file in his home directory are searched for appropriate information. 
If all this fails, the user is prompted for the information. 

The port inport specifies which well-known DARPA Internet port to use for the 
connection. The protocol for connection is described in detail in rexecd(lM). 

If the call succeeds, a socket of type SOCK__STREAM is returned to the caller, and 
given to the remote command as its standard input and standard output. If fd2p 
is non-zero, then a auxiliary channel to a control process will be setup, and a 
descriptor for it will be placed in *fd2p. The control process will return diagnos- 
tic output from the command (unit 2) on this channel, and will also accept bytes 
on this channel as signal numbers, to be forwarded to the process group of the 
command. If fd2p is 0, then the standard error (unit 2 of the remote command) 
will be made the same as its standard output and no provision is made for send- 
ing arbitrary signals to the remote process, although you may be able to get its 
attention by using out-of-band data. 

SEE ALSO 

gethostentON), getservent(3N), rcmd(3N), rexecd(lM). 

NOTES 

There is no way to specify options to the socket ( ) call that rexec ( ) makes. 
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NAME 

rpc - library routines for remote procedure calls 
DESCRIPTION 

RPC routines allow C language programs to make procedure calls on other 
machines across a network. First, the client calls a procedure to send a data 
packet to the server. On receipt of the packet, the server calls a dispatch routine 
to perform the requested service, and then sends back a reply. 

The following sections describe data objects use by the RPC package. 

Nettype 

Some of the high-level RPC interface routines take a nettype string as one of the 
parameters [for example, clntjcreate, svcjcreate, rpc_reg, rpc_call]. This 
string defines a class of transports which can be used for a particular application. 
The transports are tried in left to right order in the NETPATH variable or in top to 
down order in the /etc/netconf ig file. 

nettype can be one of the following: 

netpath Choose from the transports which have been indicated by their 

token names in the NETPATH variable. If NETPATH is unset or 
NULL, it defaults to visible, netpath is the defauU nettype. 

visible Choose the transports which have the visible flag (v) set in the 

/etc/netconf ig file. 

circuit_v This is same as visible except that it chooses only the connec- 
tion oriented transports from the entries in /etc/netconfig 
file. 

datagrainjv This is same as visible except that it chooses only the connec- 
tionless datagram transports from the entries in 
/etc/netconfig file. 

circuit_n This is same as netpatJi except that it chooses only the connec- 
tion oriented datagram transports 

datagramjn This is same as netpath except that it chooses only the connec- 
tionless datagram transports. 

udp It refers to Internet UDP. 

tcp It refers to Internet TCP. 

raw This is for memory based RPC, mainly for performance evalua- 

tion. 

If nettype is NULL, it defaults to netpath. 
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Data Structures 

Some of the data structures used by the RPC package are shown below. 
The AUTH Structure 

union des^block { 
struct { 

u_int32 high; 

u_int32 low; 
> Icey; 
char c[8]; 



typedef union des^blodc desjDlock; 
extem booljt xdrjie8_block() ; 

/* 

* Authentication info. Opaqiue to client. 
*/ 

struct opaque_auth { 

enumjt oa_flavor; /* flavor of auth */ 
caddrjt oajdase; /* address of more auth stuff */ 
u_int oa_length; /* not to exceed MftXJtfJTH_BYTBS */ 



/* 

* Auth handle, interface to client side authenticators. 
*/ 

typedef struct { 

struct opaquejELUth ahjcred; 
struct opaque_auth ahjverf; 
union desjDlock ahjcey; 
struct authjops { 

void (*ah_nextverf ) () ; 

int (*ah_inarshal) (); /* nextverf & serialize */ 
int (*ah_validate) () ; /* validate varif ier */ 
int (*ah_refresh) () ; /* refresh credentials V 
void (*ahjdestroy) (); /* destroy this structure V 
> *ahjops; 
caddrjt ah_private; 
} AUTH; 

The CLIENT structure 
/* 

* Client rpc handle. 

* Created by individual inplementations 

* Client is responsible for initializing auth, see e.g. authjnone.c. 
*/ 

typedef struct { 

AUTH *cl_auth; /* authenticator */ 

struct clntjops { 



enum clnt_stat (*cl_call) (); /* call remote procedure */ 



>; 



>; 



void 
bool t 



bool t 



void 
void 



(*cl_abort) () ; 
(*cl_geterr) () ; 
(*cl_freeres) () ; 
(*cl_destroy) (); 
(*cl_control) (); 



/* abort a call */ 
/* get specific error code */ 
/* frees results */ 
/* destroy this structure */ 
/* the ioctlO of rpc */ 
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) *clj)ps; 
caddr__t 
char 
char 
} CLIENT; 

The svcxPRT Structure 

enum jqprt_8tat { 
XPRTJDIBD, 
XPRTJ40BBRBQS, 
XPRT IDLE 

>; 



cl_private; 

*cl_netid; 

*cljtp; 



/* private stuff */ 
/* netiiorlc token */ 
/* device name */ 



* Server side tranafport handle 
V 

typedBf struct { 

xp_fd; 



int 

#def ine 3qp)_sock 
tendif 

u short 



xp_fd 
3q>j>ort; 



/* associated port nunter. 

* C^solete, but still used to 

* specify tdiether rendezvouser 

* or normal connection 



struct xpjops { 
bool_t 

en\2m xprt_stat 

boolj: 

bool_t 

bool_t 

void 
} *xp_ops; 
int 
char 
char 

struct netbuf 
struct netbuf 
char 



(*:q>_recv) (); 
(*:q>_stat) 0; 
(*3q>_getargs) (); 
(*:q)_reply) () ; 
(*3q>_freeargs) (); 
(*3q?jdestroy) (); 



3qp_addrlen; 
*xpjtp; 
*xpjietid; 

3q>_ltaddr; 
^_rtaddr; 
xp__r addr [16]; 



struct opaque_auth :q>jv©rf ; 
caddr_t 3q>j>l; 
caddrj: 3q>j)2; 
caddr_t xpjp3; 
) SVCXPRT; 



/* receive incoming requests */ 
/* get transport status */ 
/* get arguments */ 
/* send reply */ 

/* free mem allocated for args */ 
/* destroy this struct */ 

/* length of remote addr. CS^solete */ 

/* transport provider device name */ 

/* network token */ 

/* local transport address */ 

/* remote transport address */ 

/* remote address. Obsolete */ 

/* raw response verifier */ 

/* private: for use by svc ops */ 

/* private: for use by svc ops */ 

/* private: for use by svc lib */ 



The XDR Structure 
/* 

* Xdr operations. XDR_ENCODE causes the type to be encoded into the 

* stream. XDR_DECCX)E causes the type to be extracted from the stream. 

* XI^JBREE can be used to release the space allocated by an XDRJ)ECODE 

* request. 
V 

enum xdrjop { 

XDR_ENCODE-0, 
XDR DEOODE-1, 
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XDR FREE-'2 



}; 



* This is tbe nunber of bytes per imit of external data. 



♦define BrrES_PERJCDR_UNIT (4) 
idef ine KNDUP (x) ( ( ( (x) + BYTBS_PER_XDR_UMIT 
* BYTES PER XDR UNIT) 



1) / BYTES PER XDR UNIT) \ 



* A xdrprocjt exists for each data type Khich is to be encoded or decoded. 
* 

* The second argument to the xdzproc^jt is a pointer to an opaque pointer. 

* The opaque pointer generally points to a structure of the data type 

* to be decoded. If this pointer is 0, then the type routines should 

* allocate dynamic storage of the appropriate size and return it. 

* boolj: (*xdrprocJt) (XDR *, caddrj: *) ; 
*/ 

typedef bool_t (*xdrprocJ:) () ; 
/* 

* The XDR handle. 

* Contains operation which is being applied to the stream, 

* an operations vector for the paticular implementation (e.g. see xdrjnem.c), 

* and two private fields for the use of the particular inpelementation. 



typedef struct { 

enum xdr_op x_pp; 
struct xdrjops { 

booljt ( *x_get long) ( ) ; 



/* operation; fast additional param */ 



boolt 
booljt 
boolt 
u_int 
boolt 
long * 
void 
> *xj>ps; 
caddrjt 
caddrjt 
caddrjt 
int 
} XDR; 



/* get a long from underlying stream 
/* put a long to " */ 
/* get some bytes from " */ 
/* put some bytes to " */ 
(*xjgetpostn) () ; /* returns bytes off from beginning */ 
(*x_setpostn) () ; /* lets you reposition the stream */ 
/* buf quick ptr to buffered data */ 
/* free privates of this xdr_stream */ 



(*x_putlong) 0; 
(*x_getbytes) () ; 
(*xjputbytes) () ; 



(*x__inline) () ; 
(*x_destroy) (); 



xjjublic; /* users' data */ 

x_private; /* pointer to private data */ 

xjdase; /* private used for position info */ 

xjiandy; /* extra private word */ 



Index to Routines 

The following table lists RPC routines and the manual reference pages on which 
they are described: 
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RPC Routine 

authjdlestrqy 

authdesjgetucred 

authdes_seocreate 

authnonejcreate 

authsys_create 

authsys_create_default 

clntjcall 

clntjcontrol 

clntjcreate 

clntjiestrqy 

clntjdgjcreate 

clnt_freeres 

clnt_geterr 

clnt_j>createerror 

clnt_perrno 

clnt_perror 

clnt_rawjcreate 

clnt_spcreateerror 

clnt_sperrno 

clntjsperror 

clntjtli_create 

clntjtp_create 

clntjvcjcreate 

getnetnaxne 

host2netnaine 

keyjdecryptsession 

key_encryptsession 

keyjgendes 

key_setsecret 

netnanie2host 

netndine2user 

rpc^broadcast 

rpc_call 

rpc_reg 

svc_create 

svcjdestroy 

svc__dg_create 

svc_fd_create 

svc_freeargs 

svcjgetargs 

svcjgetreqset 

svc_getrpccaller 

svc__rawjcreate 

svcjreg 

svc__run 

svc_sendreply 



Manual Reference Page 
rpcjclntjauth(3N) 
secure_rpc(3^D 
secure_rpc(3N) 
rpc_clntjauth(3N) 
rpcjclntjauth(3N) 
rpcjclntjauth(3N) 
rpc_clntjcalls(3N) 
rpcjclntjcreate(3N) 
rpcjclntjDreate(3N) 
rpcjclntjcreate(3N) 
rpcjclntjcreate(3N) 
rpc_clntjcalls(3ND 
rpcjclntjcalls(3ND 
rpc_clntjcreate(3N) 
rpc_clntjcalls(3N) 
rpc__clntjcalls(3N) 
rpcjclntjcreateON) 
rpc_clntjcreate(3N) 
rpcjclntjcallsON) 
rpc_clnt_calls(3N) 
rpc_clntjcreate(3N) 
rpc_clntjcreate(3N) 
rpc_clnt_create(3N) 
secure_rpc(3N) 
secure_rpc(3N) 
secure__rpc(3N) 
secure_rpc(3N) 
secure_rpc(3N) 
secure_rpc(3N) 
secure_rpc(3N) 
securejcpc(3N) 
rpc_clntjcalls(3N) 
rpc__clntjcalls(3N) 
rpc_svc_calls(3N) 
rpc_svc_create(3N) 
rpc_svcjcreate(3N) 
rpc_svcjcreate(3N) 
rpc_svcjcreate(3N) 
rpc_svcjt:eg(3N) 
rpc_svcj:eg(3N) 
rpc_svc__reg(3N) 
rpc__svcj:eg(3N) 
rpc__svc_create(3N) 
rpc__svc_calls(3N) 
rpc_svc_reg(3N) 
rpc_svc_reg(3ND 
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FILES 



svcjtlijcreate 

svcjtpjcreate 

svcjanreg 

svc_yc_create 

i5vcerr_auth 

svcerrjieocxie 

svcerrjtipproc 

svcerr_nqprog 

svcerr_progvers 

svcerr_systemerr 

svcerrjweakauth 

user2netnaxne 

xdrjacceptedjreply 

xdrjauthsys^parms 

xdrjcallhdr 

xdrjcallmsg 

xdrjopaque_auth 

xdr_re jected^reply 

xdrjreplyinsg 

:qprt_register 

xprtjunregister 

/etc/netconfig 



rpc_svcjcreate(3N) 

rpc_svcjcreate(3N) 

rpcjBvcjcallsOND 

rpcjBvcjC5reate(3N) 

rpc_8vcjBrr(3N) 

rpc_svcjBrr(3N) 

rpc_svcjerr(3hD 

rpc_svcjerr(3N) 

rpc_svcjBrr(3N) 

rpc_svcjBrr(3N) 

rpc_svcjerr(3N) 

secure_rpc(3N) 

rpejxdr(3N) 

rpcjcdr(3N) 

rpcjcdr(3N) 

rpc_xdr(3N) 

rpcjjcdr(3N) 

rpc_x<ir(3N) 

rpc_xdr(3N) 

rpc_svcjcalls(3N) 

rpc_svc_calls(3N) 



SEE ALSO 

environ(5), getnetconfig(3N), getnetpath(3N), rpcjclnt_auth(3ND, 
rpCJClnt_calls(3^D, rpc_clnt_create(3N), i:pc_svc_jcalls(3N), 
rpcjBvc_create(3N), rpc_svc_err(3ND, rpcjsvc_reg(3N), rpc_xdr(3N), 
rpcbind(3N), secure_rpc(3N), xdr(3N), netoonf ig(4). 
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NAME 

rpc_clnt_auth: authjdestroy, authnone__create, authsysjcreate, 

authsys_create_def ault - library routines for client side remote procedure call 
authentication 

DESCRIPTION 

These routines are part of the RPC library that allows C language programs to 
make procedure calls on other machines across the network, with desired authen- 
tication. First, the client calls a procedure to send a data packet to the server. 
Upon receipt of the packet, the server calls a dispatch routine to perform the 
requested service, and then sends back a reply. 

These routines are normally called after creating the CLIENT handle. The client's 
authentication information is passed to the server when the RPC call is made. 

Routines 

The following routines require that the header rpc.h be included [see rpc(3N) 
for the definition of the AUTH data structure]. 

finclude <rpc/rpc.h> 

void 

authjdestroy (AUTH *auth) ; 

A function macro that destroys the authentication information associated 
with auth. Destruction usually involves deallocation of private data struc- 
tures. The use of auth is undefined after calling authjdestroy. 

AUTH * 

authnonejcreate (void) / 

Create and return an RPC authentication handle that passes nonusable 
authentication information with each remote procedure call. This is the 
default authentication used by RPC. 

AUTH * 

authsysjcreate (const char *host, const uid_t uid, const gid_t gid, 
const int len, const gid_t *aupjgids) ; 

Create and return an RPC authentication handle that contains AUTH_SYS 
authentication information. The parameter host is the name of the 
machine on which the information was created; uid is the user's user ID; 
gid is the user's current group ID; ten and aup ^gids refer to a counted array 
of groups to which the user belongs. 

AUTH * 

authsys_create__def ault (void) ; 

Call autJisysjcreate with the appropriate parameters. 

SEE ALSO 

rpc(3N), rpc_clntjcreate(3N), rpc_clnt_calls(3N). 
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NAME 

rpcjclntjcalls: clntjcall, clnt_freeres, clnt_geterr, clnt_perrno, 
clntjperror, clntjsperrno, clntjsperror, zpcJ>roadcast, rpcjcall - 
library routines for client side calls 

DESCRIPTION 

RPC library routines allow C language programs to make procedure calls on 
other machines across the network. First, the client calls a procedure to send a 
data packet to the server. Upon receipt of the packet, the server calls a dispatch 
routine to perform the requested service, and then sends back a reply. 

The clnt_call, rpcjcall and zpcjDroadcast routines handle the client side of 
the procedure call. The remaining routines deal with error handling in the case 
of errors. 

Routines 

See rpc(3N) for the definition of the CLIENT data structure, 
♦include <rpc/rpc.h> 
enum clnt_stat 

clntjcall (CLIENT *clnt/ const u_long procnum^ const xdrprocjt inproc, 
caddr_t in, const xdrprocjt outproc, caddr_t out, 
const struct timeval tout); 

A fimction macro that calls the remote procedure procnum associated with 
the client handle, clnt, which is obtained with an RPC client creation rou- 
tine such as clntjcreate [see rpc_clnt_create(3N)]. The parameter in is 
the address of the procedure's argument(s), and out is the address of 
where to place the result(s); inproc is used to encode the procedure's 
parameters, and outproc is used to decode the procedure's results; tout is 
the time allowed for results to be returned. 

If the remote call succeeds, the status is returned in RPCJSUCCESS, others 
wise an appropriate status is returned. 

int clnt_freeres (CLIENT *clnt, const xdrproc_t outproc, caddr_t out) ; 

A function macro that frees any data allocated by the RPC/XDR system 
when it decoded the results of an RPC call. The parameter out is the 
address of the results, and outproc is the XDR routine describing the 
results. This routine returns 1 if the results were successfully freed, and 0 
otherwise. 

void 

clnt jgeterr (const CLIENT *clnt, struct rpc_err *errp); 

A function macro that copies the error structure out of the client handle to 
the structure at address errp. 
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void 

clnt_perrno (const enum clntj9tat stat) ; 

Print a message to standard error corresponding to the condition indicated 
by Stat. A newline is appended at the end of the message. Normally used 
after a procedure call fails, for instance rpcjcall. 

void 

clntjperror (const CLIENT *clntr const char *s) ; 

Print a message to standard error indicating why an RPC call failed; clnt is 
the handle used to do the call. The message is prepended with string s 
and a colon. A newline is appended at the end of the message. Normally 
used after a procedure call fails, for instance clntjcall. 

char * 

clnt_spermo (const envrm clnt_stat stat); 

Take the same arguments as clnt_j>errno, but instead of sending a mes- 
sage to the standard error indicating why an RPC call failed, return a 
pointer to a string which contains the message. 

clnt_spermo is normally used instead of clnt__perrno when the pro- 
gram does not have a standard error (as a program running as a server 
quite likely does not), or if the programmer does not want the message to 
be output with printf [see printf(3S)], or if a message format different 
than that supported by clnt_permo is to be used. Note: unlike 
clnt_sperror and clnt_spcreaterror [see rpc_clnt_create(3N)], 
clnt__spermo does not return pointer to static data so the result will not 
get overwritten on each call. 

char * 

clnt_sperror (const CLIENT *clntr const char *s) ; 

Like clnt_j>error, except that (like clnt_spermo) it returns a string 
instead of printing to standard error. However, clnt_sperror does not 
append a newline at the end of the message. 

Warning: returns pointer to static data that is overwritten on each call. 
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enum clnt_stat 

zpcjbroadcast (const u_long prognvun, const u_long versnvunr 

const u_long procnimir const xdrproc_t inproc^ caddr_t in, 

const xdrprocjt outproc, caddrjt out, const resultproc_t eachresult, 

const char *nettype); 

Like rpc_call, except the call message is broadcast to the connectionless 
network specified by nettype. If nettype is WJLL, it defaults to netpath. 
Each time it receives a response, this routine calls eachresult, whose 
form is: 

booljt 

eachresult (const caddrjb out, const struct netbuf *addr, 
struct netconfig *netconf); 

where out is the same as out passed to rpcjDroadcast, except that the 
remote procedure's output is decoded there; addr points to the address of 
the machine that sent the results, and netconf is the netconfig structure of 
the transport on which the remote server responded. If eachresult 
returns 0, rpc_broadcast waits for more replies; otherwise it returns 
with appropriate status. 

Warning: broadcast file descriptors are limited in size to the maximum 
transfer size of that transport. For Ethernet, this value is 1500 bytes. 

enum clnt_stat 

rpc_call (const char *host, const u__long prognum, 
const u_long versnum, const u_long procnum, 
const xdrprocjt inproc, const xdrprocjt outproc, 
const char *in, char *out, const char *nettype) ; 

Call the remote procedure associated with prognum, versnum, and procnum 
on the machine, host. The parameter in is the address of the procedure's 
argimient(s), and out is the address of where to place the result(s); inproc is 
used to encode the procedure's parameters, and outproc is used to decode 
the procedure's results, nettype can be any of the values listed on 
rpc(3N). If nettype is NULL, it defaults to netpath. This routine returns 0 
if it succeeds, or the value of enum clntjstat cast to an integer if it fails. 
Use the clnt_perrno routine to translate failure statuses into messages. 

Warning: rpc_call uses the first available transport belonging to the class 
nettype, on which it can create a connection. You do not have control of 
timeouts or authentication using this routine. There is also no way to des- 
troy the client handle. 

SEE ALSO 

printf (3S), rpc(3ND, rpc_clnt_auth(3N), rpc_clnt_create(3N). 
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NAME 

rpc_clnt_jcreate: clnt_control, clntjcreate, clntjdestroy, 
clntjdgjcreate, clnt_pcreateerror, clnt_rawjcreate, 
clntjspcreateerror, clnt_tli_create, clnt_tpjcreate, clnt_ycjcreate - 
library routines for dealing with creation and manipulation of CLIENT handles 

DESCRIPTION 

RFC library routines allow C language programs to make procedure calls on 
other macWnes across the network. First a CLIENT handle is created and then the 
client calls a procedure to send a data packet to the server. Upon receipt of the 
packet, the server calls a dispatch routine to perform the requested service, and 
then sends back a reply. 

Routines 

See rpc(3N) for the definition of the CLIENT data structure. 

♦include <rpc/rpc.h> 

booljt 

clntjcontrol (CLIENT *clnt, const u_int req, char *info) ; 

A function macro used to change or retrieve various information about a 
client object, recj indicates the type of operation, and info is a pointer to 
the information. For both connectionless and connection-oriented tran- 
sports, the supported values of req and their argument types and what 
they do are: 



CLSETjriMEODT struct timeval set total timeout 
CLGETjriMEOCJT Struct timeval get total timeout 

Note: if you set the timeout using clntjcontrol, the timeout parameter 
passed to clntjcall will be ignored in all future calls. 



CLGET_FD 
CLGET_SVCJVDDR 
CLSET FD CLOSE 



int 

struct netJauf 
int 



CLSET FD NCLOSE int 



get the associated file descriptor 
*get servers address 
close the file descriptor when 
destroying the client handle 
[see clntjdestroy] 
do not close the file 
descriptor when destrojdng 
the client handle 



The following operations are valid for connectionless transports only: 



CLSET^RETRYjriMEOOT struct timeval set the retry timeout 
CLGET^RETRYjriMEOOT struct timeval get the retry timeout 

The retry timeout is the time that RFC waits for the server to reply before 
retransmitting the request. 
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clntjcontrol returns 1 on success and 0 on failure. 
CLIENT * 

clntjcreate (const char *ho8t^ const u_long prognum, 
const u_long versnum, const char *nettype) ; 

Generic client creation routine for program prognum and version versnum. 
host identifies the name of the remote host where the server is located. 
nettype indicates the class of transport protocol to use. The transports are 
tried in left to right order in NETPATH variable or in top to down order in 
the netconfig database. 

clntjcreate tries all the transports of the nettype class available from the 
NETPATH environment variable and the the netconfig database, and 
chooses the first successful one. Default timeouts are set, but can be 
modified using clntjcontrol. 

void 

clntjdestroy (CLIENT *clnt) ; 

A function macro that destro)^ the client's RPC handle. Destruction usu- 
ally involves deallocation of private data structures, including clnt itself. 
Use of clnt is xmdefined after calling clntjdestroy. If the RPC library 
opened the associated file descriptor, or CLSET_FDjCLOSE was set using 
clntjcontrol, it will be closed. 

CLIENT * 

clntjdgjcreate (const int fd^ const struct netbuf *svcaddr, 
const u_long prognum, const u_long versnum, 
const u_int sendsz, const u_int recvsz) ; 

This routine creates an RPC client for the remote program prognum and 
version versnum; the client uses a connectionless transport. The remote 
program is located at address svcaddr. The parameter fd is an open and 
bound file descriptor. This routine will resend the call message in inter- 
vals of 15 seconils until a response is received or until the call times out. 
The total time for the call to time out is specified by clntjcall [see 
clntjcall in rpc_clntjcalls(3N)]. This routine returns NULL if it fails. 
The retry time out and the total time out periods can be changed using 
clntjcontrol. The user may set the size of the send and receive buffers 
with the parameters sendsz and recvsz; values of 0 choose suitable defaults. 

void 

clnt_pcreateerror (const char *s) ; 

Print a message to standard error indicating why a client RPC handle 
could not be created. The message is prepended with the string s and a 
colon, and appended with a newline. 
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CLIENT * 

clnt_rawjcreate (const u_long prognum, const u_long versnum) ; 

This routine creates a toy RPC client for the remote program prognum and 
version versnum. The transport used to pass messages to the service is a 
buffer within the process's address space, so the corresponding RPC 
server should live in the same address space; [see svc_raw_create in 
rpc_clntjcalls(3N)]. This allows simulation of RPC and acquisition of 
RPC overheads, such as round trip times, without any kernel interference. 
This routine returns NULL if it fails. clnt_rawjcreate should be called 
after svc_rawjcreate. 

char * 

c Intjspcr eat eerror (const char *s) ; 

Like clnt_pcreateerror, except that it returns a string instead of print- 
ing to the standard error. A newline is not appended to the message in 
this case. 

Warning: returns a pointer to static data that is overwritten on each call. 
CLIENT * 

clntjtli__create (const int fd, const struct netconfig *netconf, 
const struct netJDuf *svcaddr, u const__long prognimi, 
const u__long versnum, const u_int sends 
const u_int recvsz) ; 

This routine creates an RPC client handle for the remote program prognum 
and version versnum. The remote program is located at address svcaddr. 
If svcaddr is NULL and it is connection-oriented, it is assumed that the file 
descriptor is connected. For connectionless transports, if svcaddr is NULL, 
RPCJCJNKNOWNADDR error is set. fd is a file descriptor which may be open, 
bound and connected. If it is RPC_ANYFD, it opens a file descriptor on the 
transport specified by netconf. If netconf is NULL, a RPCJUNKNOWNPROTO 
error is set. If fd is unboimd, then it will attempt to bind the descriptor. 
The user may specify the size of the buffers with the parameters sendsz 
and recvsz; values of 0 choose suitable defaults. Depending upon the type 
of the transport (connection-oriented or connectionless), clnt__tli_create 
calls appropriate client creation routines. This routine returns NULL if it 
fails. The clnt_pcreaterror routine can be used to print the reason for 
failure. The remote rpcbind service [see rpcbind(lM)] will not be con- 
sulted for the address of the remote service. 

CLIENT * 

clnt_tp_create (const char *host, const u_long prognum, 

const u_long versnum, const struct netconfig *netconf ) ; 

clntjtpjcreate creates a client handle for the transport specified by 
netconf. Default options are set, which can be changed using 
clntjcontrol calls. The remote rpcbind service on the host host is con- 
sulted for the address of the remote service. This routine returns NULL if 
it fails. The clnt_pcreaterror routine can be used to print the reason 
for failure. 
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CLIENT * 

clnt_yc_create (cxjnst int fd, const struct netbuf *svcaddrr 
const u_long prognum, const u_long versnum, 
const u_int sendsz, const u_int recvsz); 

This routine creates an Rrc client for the remote program prognum and 
version versnum; the client uses a connection-oriented transport. The 
remote program is located at address svcaddr. The parameter fd is an open 
and bound file descriptor. The user may specify the size of the send and 
receive buffers with the parameters sendsz and recvsz; values of 0 choose 
suitable defaults. This routine returns NULL if it fails. 

The address svcaddr should not be NULL and should point to the actual 
address of the remote program. clnt_vcjcxeate will not consult the 
remote rpcbind service for this information. 

SEE ALSO 

rpcbinddM), rpc(3N), rpc_clnt_auth(3N), rpcjclnt_calls(3ND. 
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NAME 

rpc_svcjcalls: rpc_reg, svc_reg, svcjunreg, xprt_register, 
xprt janregister - library routines for registering servers 

DESCRIPTION 

These routines are a part of the RPC library which allows the RFC servers to 
register themselves with rpcbind [see rpcbind(lM)], and it associates the given 
program and version number with the dispatch function. 

Routines 

See rpc(3N) for the definition of the SVCXPRT data structure. 

♦include <rpc/rpc.h> 

int 

rpc_reg (const u_long prognum, const u_long versnum, 
const u_long procnian, const char * (^procname) , 
const xdrprocjt inproc^ const xdrprocjt outproc, 
const char *nettype); 

Register program prognum, procedure procname, and version versnum with 
the RPC service package. If a request arrives for program prognum, ver- 
sion versnum, and procedure procnum, procname is called with a pointer to 
its parameter(s); procname should return a pointer to its static result(s); 
inproc is used to decode the parameters while outproc is used to encode the 
results. Procedures are registered on all available transports of the class 
nettype. nettype defines a class of transports which can be used for a par- 
ticular application. If nettype is NULL, it defaults to netpath. This routine 
returns 0 if the registration succeeded, -1 otherwise. 

int 

svc_j:eg (const SVCXPRT *:qprt, const u_long prognum, const u_long versnum, 
const void (^dispatch) , const struct netconf ig *netconf ) / 

Associates prognum and versnum with the service dispatch procedure, 
dispatch. If netconf is NULL, the service is not registered with the rpcbind 
service. If netconf is non-zero, then a mapping of the triple [prognum, vers- 
num, «^teon/->nc_netid] to :tpri->xp_ltaddr is established with the local 
rpcbind service. 

The svc_reg routine returns 1 if it succeeds, and 0 otherwise 

void 

svcjunreg (const u_long prognum, const u_long versnum); 

Remove, from the rpcbind service, all mappings of the double [prognum, 
versnum] to dispatch routines, and of the triple [prognum, versnum, *] to 
network address. 
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void 

xprtjcegister (const SVCXPRT *xprt) ; 

After RPC service transport handle xprt is created, it is registered with the 
RPC service package. This routine modifies the global variable svc_fds. 
Service implementors usually do not need this routine. 

void 

3{prtjunregister (const SVCXPRT *xprt) ; 

Before an RPC service transport handle xprt is destroyed, it unregisters 
itself with the RPC service package. This routine modifies the global vari- 
able svc_f ds. Service implementors usually do not need this routine. 

SEE ALSO 

rpcbinddM), rpcbind(3^D/ rpcON), rpcjBvc_err(3N), rpcjsvcjcreate(3N), 
rpcjsvc_reg(3N). 
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NAME 

rpc^svcjcreate: svcjcreate, svcjdestroy, svcjdgjcreate, 8vc__fdjcreate, 
svc_raw_create, svcjtlijcreate, 8vc_tp_create, svc^vcjcreate - library 
routines for dealing with the creation of server handles 

DESCRIPTION 

These routines are part of the RPC library which allows C language programs to 
make procedure calls on servers across the network. These routines deal with the 
creation of service handles. Once the handle is created, the server can be invoked 
by calling svcjcun. 

Routines 

See rpc(3N) for the definition of the SVCXPRT data structure. 

♦include <rpc/rpc.h> 

int 

svc__create ( 

const void (*dispatch) (const struct svc_req *, const SVCXPRT *) , 
const u_long prognum, const u_long versnum, 
const char *nettype); 

svcjcreate creates server handles for all the transports belonging to the 
class nettype. 

nettype defines a class of transports which can be used for a particular 
application. The transports are tried in left to right order in NETPATH vari- 
able or in top to down order in the netconfig database. 

If nettype is NULL, it defaults to netpatJi. svcjcreate registers itself with 
the rpcbind service [see rpcbinddM)]. dispatch is called when there is a 
remote procedure call for the given prognum and versnum; this requires 
calling svc_run [see svc_run in rpc_svc_reg(3N)]. If it succeeds, 
svcjcxeate returns the number of server handles it created, otherwise it 
returns 0 and the error message is logged. 

void 

svc_destroy (SVCXPRT *xprt) ; 

A function macro that destroys the RPC service transport handle xprt. 
Destruction usually involves deallocation of private data structures, 
including xprt itself. Use of xprt is undefined after calling this routine. 

SVCXPRT * 

svc_dg_create (const int fd, const u_int sendsz, const u__int recvsz) ; 

This routine creates a connectionless RPC service handle, and returns a 
pointer to it. This routine returns NULL if it fails, and an error message is 
logged, sendsz and recvsz are parameters used to specify the size of the 
buffers. If they are 0, suitable defaults are chosen. The file descriptor fd 
should be open and bound. 

Warning: since connectionless-based RPC messages can only hold limited 
amount of encoded data, this transport cannot be used for procedures that 
take large arguments or return huge results. 
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SVCXPRT * 

svc^fdjcreate (const int fd, const u_int sendsz, const u_int recvsz) ; 

This routine creates a service on top of any open and bound descriptor, 
and returns the handle to it. Tj^ically, this descriptor is a connected file 
descriptor for a connection-oriented transport, seiidsz and recvsz indicate 
sizes for the send and receive buffers. If they are 0, a reasonable default 
is chosen. This routine returns NULL, if it fails, and an error message is 
logged. 

SVCXPRT * 

svcjcawjcreate (void) ; 

This routine creates a toy RPC service transport, to which it returns a 
pointer. The transport is really a buffer within the process's address 
space, so the corresponding RPC client should live in the same address 
space; [see clnt_rawjcreate in rpc clnt create]. This routine allows 
simulation of RPC and acquisition of RPC overheads (such as round trip 
times), without any kernel interference. This routine returns NULL if it 
fails, and an error message is logged. 

SVCXPRT * 

svcjtlijcreate (const int fd, const struct netconfig *netconf, 
const struct tjaind *bindaddr, const u_int sendsz, 
const u__int recvsz); 

This routine creates an RPC server handle, and returns a pointer to it. fd 
is the fQe descriptor on which the service is listening. If fd is RPC_ANYFD, it 
opens a file descriptor on the transport specified by neiconf. If the file 
descriptor is unbound, it is bound to the address specified by bindaddr, if 
bindaddr is non-null, otherwise it is botmd to a default address chosen by 
the transport. In the case where the default address is chosen, the number 
of outstanding connect requests is set to 8 for connection-oriented tran- 
sports. The user may specify the size of the send and receive buffers with 
the parameters sendsz and recvsz; values of 0 choose suitable defaults. 
This routine returns NULL if it fails, and an error message is logged. 

SVCPRT * 

svcjtpjcreate (const void (*dispatch) (const RQSTP const SVCXPRT *) , 
const u_long prognum, const u__long versnum, 
const struct netconfig *netconf ) ; 

svcjtpjcreate creates a server handle for the network specified by 
netconf, and registers itself with the rpdDind service, dispatch is called 
when there is a remote procedure call fbr the given prognum and versnum; 
this requires calling svc_run. svcjtpjcreate returns the service handle 
if it succeeds, otherwise a NULL is returned, and an error message is 
logged. 
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SVCXPRT * 

svc_vc_jcreate (const int fd, cx>nst u_int sends const u_int recvsz) ; 

This routine creates a connection-oriented RPC service and returns a 
pointer to it. This routine returns NULL if it fails, and an error message is 
logged. The users may specify the size of the send and receive btrffers 
with the parameters sendsz and recvsz; values of 0 choose suitable defaults. 
The file descriptor fd should be open and bound. 

SEE ALSO 

rpcbind(lM), rpc(3N), rpcjBvcjcalls(3N), rpc_svcjBrr(3N)/ 
rpc_svc_reg(3N). 
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NAME 

rpc_svc_jerr: svcerr_auth, svcerrjdeocxie, svcerrjiqproc, 
svcerr^npprog, svcerr__progvers, svcerr^systemerr, svcerr_weakauth - 
library routines for server side remote procedure call errors 

DESCRIPTION 

These routines are part of the RFC library which allows C language programs to 
make procedure calls on other machines across the network. 

These routines can be called by the server side dispatch function if there is any 
error in the transaction with the client. 

Routines 

See xpc(3N) for the definition of the SVCXPRT data structure. 

♦include <rpc/rpc.h> 

void 

svcerrjauth (const SVCXPRT *xprt, const enum aut:h_stat why); 

Called by a service dispatch routine that refuses to perform a remote pro- 
cedure call due to an authentication error. 

void 

svcerrjdecode (const SVCXPRT *xprt) ; 

Called by a service dispatch routine that cannot successfully decode the 
remote parameters [see svcjgetargs in rpc_svcjreg(3N)]. 

void 

svcerr_noproc (const SVCXPRT *xprt) ; 

Called by a service dispatch routine that does not implement the pro- 
cedure number that the caller requests. 

void 

svcerrjnoprog (const SVCXPRT *3^rt) ; 

Called when the desired program is not registered with the RFC package. 
Service implementors usually do not need this routine. 

void 

svcerr_progvers (const SVCXPRT *xprt) ; 

Called when the desired version of a program is not registered with the 
RFC package. Service implementors usually do not need this routine. 

void 

svcerr^systemerr (const SVCXPRT *xprt) ; 

Called by a service dispatch routine when it detects a system error not 
covered by any particular protocol. For example, if a service can no 
longer allocate storage, it may call this routine. 
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void 

8vcerrj#eakauth (const SVCXPRT ""xprt) ; 

Called by a service dispatch routine that refuses to perform a remote pro- 
cedure call due to insufficient (but correct) authentication parameters. The 
routine calls svcerrjauth(3q>rt, AUTHJEOOWEAK) . 

SEE ALSO 

rpc(3N), rpc_svcjcalls(3N), rpcjBvc_create(3N), rpcjsvcj:eg(3N). 
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NAME 

rpc_svc_reg: svc_f reeargs, svcjgetargs, svcjgetreqset, 
svcjgetrpccaller, svcjrun, svc_sendreply - library routines for RPC servers 

DESCRIPTION 

These routines are part of the RPC library which allows C language programs to 
make procedure calls on other machines across the network. 

These routines are associated with the server side of the RPC mechanism. Some 
of them are called by the server side dispatch function, while others [such as 
svc_run] are called when the server is initiated. 

Routines 

♦include <rpc/rpc.h> 

int 

svc_freeargs (const SVCXPRT *xprt, const xdrproc_t inproc, char *in) ; 

A function macro that frees any data allocated by the RPC/XDR system 
when it decoded the arguments to a service procedure using 
svcjgetargs. This routine returns 1 if the results were successfully freed, 
and 0 otherwise. 

int 

svcjgetargs (const SVCXPRT *35prt, const xdrprocjt inproc, caddr_t *in) ; 

A function macro that decodes the arguments of an RPC request associ- 
ated with the RPC service transport handle xprt. The parameter in is the 
address where the arguments will be placed; inproc is the XDR routine 
used to decode the arguments. This routine returns 1 if decoding 
succeeds, and 0 otherwise. 

void 

svcjgetreqset (f djset *rdf ds) ; 

This routine is only of interest if a service implementor does not call 
svc_run, but instead implements custom asjmchronous event processing. 
It is called when poll has determined that an RPC request has arrived on 
some RPC file descriptors; rdfds is the resultant read file descriptor bit 
mask. The routine returns when all file descriptors associated with the 
value of rdfds have been serviced 

struct netbuf * 

svcjgetrpccaller (const SVCXPRT *xprt); 

The approved way of getting the network address of the caller of a pro- 
cedure associated with the RPC service transport handle xprt. 

void 

svc_run (void) ; 

This routine never returns. It waits for RPC requests to arrive, and calls 
the appropriate service procedure using svcjgetreqset when one 
arrives. This procedure is usually waiting for a poll library call to return. 
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int 

svcjsendreply (const SVCXPRT *3qprt, const xdrproc_t outproc, 
const caddr_t *out); 

Called by an RPC service's dispatch routine to send the results of a 
remote procedure call. The parameter xprt is the request's associated tran- 
sport handle; outproc is the XDR routine which is used to encode the 
results; and out is the address of the results. This routine returns 1 if it 
succeeds, 0 otherwise. 

SEE ALSO 

poll(2), rpc(3N), rpc_svc_calls(3N), rpc_svcjcreate(3N), rpcjsvc_err(3N). 
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NAME 

rpcjcdr: xdrjaccepted_reply, xdr^authsys^parms, xcLrjcaUhdr, 
xdrjcallmsg, xdrjopaque_auth, xdrjre jectedjreply, xdrjceplymsg - XDR 
library routines for remote procedure calls 

DESCRIPTION 

These routines are used for describing the RFC messages in XDR language. They 
should normally be used by those who do not want to use the RFC package. 

Routines 

See rpc(3N) for the definition of the XDR data structure. 

♦include <rpc/rpc.h> 

booljt 

xdrjaccepted_reply (XDR *xdrs, const struct accepted_reply *ar) ; 

Used for encoding RFC reply messages. It encodes the status of the RFC 
call in the XDR language format, and in the case of success, it encodes the 
call results also. 

booljt 

xdrjauthsysjpazms (XDR *xdrs, const struct authsysj>arins *aiipp) ; 

Used for describing operating system credentials. It includes machine- 
name, uid, gid list, etc. 

void 

xdrjcallhdr (XDR *xdrs, const struct rpcjmsg *chdr) ; 

Used for describing RFC call header messages. It encodes the static part 
of the call message header in the XDR language format. It includes infor- 
mation such as transaction ID, RFC version nimiber, program and version 
number. 

booljt 

xdrjcallinsg(XDR *xdrs, const struct rpc_msg *cinsg) ; 

Used for describing RFC call messages. This includes all the RFC call 
information such as transaction ID, RFC version number, program 
number, version number, authentication information, etc. This is normally 
used by servers to determine information about the client RFC call. 

booljt 

xdr jC3paquejauth (XDR *xdrs, const struct opaquejauth *ap); 

Used for describing RFC opaque authentication information messages. 

booljt 

xdr_rejected_reply(XDR *xdrs, const struct rejectedjceply *rr) ; 

Used for describing RFC reply messages. It encodes the rejected RFC 
message in the XDR language format. The message could be rejected 
either because of version number mis-match or because of authentication 
errors. 
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bool_t 

xdrjceplyrnsg (XDR *xdrs, const struct rpc_rosg *rxnsg) / 

Used for describing RPC reply messages. It encodes all the RPC reply 
message in the XDR language format This reply could be either an accep- 
tance, rejection or NULL. 

SEE ALSO 

rpc(3N). 



Page 2 



10/89 



rpcbind(3N) 



rpcbind(3N) 



NAME 

rpcbind: rpcbjgetmaps, rpcbjgetaddr, rpcbjgettime, rpctojnntcall, 
rpcbjBet, rpctojunset - library routines for RPC bind service 

DESCRIPTION 

These routines allow client C programs to make procedure calls to the RPC 
binder service, rpcbind [see rpcbinddM)] maintains a list of mappings between 
programs and their universal addresses. 

Routines 

♦include <rpc/rpc.h> 

struct rpcblist * 

rpcbjgfetmaps (const struct netconfig *netoonf, const char *host) ; 

A user interface to the rpcbind service, which returns a list of the current 
I^C program-to-address mappings on the host named. It uses the tran- 
sport specified through netconf to contact the remote rpcbind service on 
host host This routine will return NULL, if the remote rpcbind could not 
be contacted. 

booljt 

rpcb_getaddr (const u_long prognum, const u_long versnum^ 

const struct netconfig *netconf , struct netbuf *svcaddrr 
const char *host) ; 

A user interface to the rpcbind service, which finds the address of the 
service on host that is registered with program number prognum, version 
versnum, and speaks the transport protocol associated with netconf. The 
address found is returned in svcaddr. svcaddr should be preallocated. This 
routine returns 1 if it succeeds. A return value of 0 means that the map- 
ping does not exist or that the RPC system failed to contact the remote 
rpcbind service. In the latter case, the global variable rpc_createerr 
contains the B^C status. 

booljt 

rpcbjgettime (const char *host, tixne^t *timep) ; 

This routine returns the time on host in timep. If host is NULL, 
rpcbjgettime returns the time on its own machine. This routine returns 
1 if it succeeds, 0 if it fails, rpcbjgettiitie can be used to synchronize the 
time between the client and the remote server. This routine is partictdarly 
useful for secure RPC. 
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enum clntjstat 

ipcbjcmtcall (const struct netconfig *netconfr const char *hoat, 

const u^long prognum, const u_long versniim, const u_long procnum, 

const xdrproc_t inproc, const caddr_t in, 

const xdrproc_t outproc, const caddr_t out, 

const struct tixneval tout, struct netbuf *svcaddr) ; 

A user interface to the rpcbind service, which instructs rpcbind on host 
to make an RFC call on your behalf to a procedure on that host. The 
parameter *svcaddr will be modified to the server's address if the pro- 
cedure succeeds [see rpcjcall and clntjcall in rpc_clnt_calls(3ND 
for the definitions of other parameters]. This procedure should normally 
be used for a ping and nothing else [see rpcjaroadcast in 
rpcjclntjcallsON)]. This routine allows programs to do lookup and 
call, all in one step. 

boolj: 

rpcb_set (const u_long prognum, const u_long versnum, 

const struct netconfig *netconf, const struct netbuf *svcaddr) ; 

A user interface to the rpcbind service, which establishes a mapping 
between the triple [prognum, versnum, «^fcon/~>nc_netid] and svcaddr on 
the machine's rpcbind service. The value of transport must correspond to 
a network token that is defined by the netconfig database. This routine 
returns 1 if it succeeds, 0 otherwise. [See also svc_reg in 
rpcjsvc_calls(3N)]. 

bool_t 

rpcbjunset (const u__long prognum, const u_long versnum, 
const struct netconfig *netconf ) ; 

A user interface to the rpcbind service, which destroys all mapping 
between the triple [prognum, versnum, n^con/~>ncjietid] and the address 
on the machine's rpcbind service. If netconf is NULL, rpcbjunset des- 
troj^ all mapping between the triple [prognum, versnum, *] and the 
addresses on the machine's rpcbind service. This routine returns 1 if it 
succeeds, 0 otherwise. [See also svcjunreg in rpc_svc_calls(3N)]. 

SEE ALSO 

rpcjclntjcallsON), rpcjBvcjcalls(3N), rpcbinddM), rpcinfo(lM). 
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NAME 

rusers - return information about users on remote machines 

SYNOPSIS 

tinclude <xpcsvc/rusers.h> 

int rusers (char *host, struct utnpidlearr *up) ; 

rusers fills the utanpidlearr structure with data about host, and returns 0 if suc- 
cessful. The function will fail if the imderl5dng transport does not support broad- 
cast mode. 

SEE ALSO 

rusers(l). 
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NAME 

rwall - write to specified remote machines 

SYNOPSIS 

♦include <rpcsvc/rwall.h> 

rwall (char '^host, char ^msg) ; 
DESCRIPTION 

rwall executes wall(lM) on host, host prints the string msg to all its users. It 
returns 0 if successful. 

SEE ALSO 

rwall(lM), rwallddM). 



10/89 



Page 1 



8ecure_rpc(3N) 



secure_rpc(3N) 



NAME 

secure_rpc: authdes_seccreate, authdes_getucred, getnetname, 
host2netnaine, keyjdecryptsession, keyjencryptsession, key__gendes, 
key_setsecret, netnaine2host, netnaine2user, user2netname - library routines 
for secure remote procedure calls 

DESCRIPTION 

RPC library routines allow C programs to make procedure calls on other 
machines across the network. First, the client calls a procedure to send a data 
packet to the server. Upon receipt of the packet, the server calls a dispatch rou- 
tine to perform the requested service, and then sends back a reply. 

RPC supports various authentication flavors. Among them are: 

AUTH_NONE (none) no authentication. 

AUTHjSYS Traditional UNIX®-style authentication. 

AUTHJ)ES DES encryption-based authentication. 

The authdesjgetucred and autJides_seccreate routines implement the 
AUTHJDES authentication flavor. The keyserver daemon keyserv [see 
keyserv(lM)] must be running for the AUTHJ)ES authentication system to work. 

Routines 

See rpc(3N) for the definition of the AUTH data structure. 

♦include <rpc/rpc.h> 

int 

authdesjgetucred (const struct authdesjcred *adc, uidjt *uic^, 
gid_t *gidp, short *gidleqp, 9icLt *gidlist); 

authdes_getucred is the first of the two routines which interface to the 
RPC secure authentication system known as ACJTHJ)ES. The second is 
authdes_seccreate, below. authdes__getucred is used on the server 
side for converting an AUTH_J)ES credential, which is operating system 
independent, into an AUTHJSYS credential. This routine returns 1 if it 
succeeds, 0 if it fails. 

*uidp is set to the user's numerical ID associated with ode. *gidp is set to 
the numerical ID of the group to which the user belongs. *gidlist contains 
the numerical IDs of the other groups to which the user belongs. *gidlenp 
is set to the number of valid group ID entries in -^gidlist [see 
netnaine2user, below]. 
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AUTH * 

authdes_seccreate (const char *naroe, const unsigned int window, 
const char *tiinehost, const des_block *ckey) ; 

authdes_seccreate, the second of two AUTH_DES authentication routines, 
is used on the client side to return an authentication handle that will 
enable the use of the secure authentication system. The first parameter 
name is the network name, or netmme, of the owner of the server process. 
This field usually represents a hostname derived from the utility routine 
host:2netnaxne, but could also represent a user name using 
user2netnaiiie, described below. The second field is window on the vali- 
dity of the client credential, given in seconds. A small window is more 
secure than a large one, but choosing too small of a window will increase 
the frequency of resynchronizations because of clock drift. The third 
parameter, timehost, the host's name, is optional. If it is NULL, then the 
authentication system will assume that the local clock is always in sync 
with the timehost clock, and will not attempt res)mchronizations. If a 
timehost is supplied, however, then the system will consult with the 
remote time service whenever resynchronization is required. This parame- 
ter is usually the name of the RPC server itself. The final parameter ckey 
is also optional. If it is NULL, then the authentication system will generate 
a random DES key to be used for the encrjrption of credentials. If ckey is 
supplied, then it will be used instead. 

int 

getnethame (char name [MAXNETNAMELEN+1] ) ; 

getnetnaxne installs the unique, operating-system independent netname of 
the caller in the fixed-length array name. Returns 1 if it succeeds, and 0 if 
it fails. 

int 

host2netnaine (char name [MAXNETNAMELEN+1 ] , const char *host, 
const char *domain); 

Convert from a domain-specific hostname host to an operating-system 
independent netname. Return 1 if it succeeds, and 0 if it fails. Inverse of 
netname2host. If domain is NULL, host2netname uses the default domain 
name of the machine. If host is NULL, it defaults to that machine itself. 

int 

keyjdecryptsession (const char *remotename, desjDlock *deskey) ; 

keyjlecryptsesiion is an interface to the keyserver daemon, which is 
associated with RPC's secure authentication system (AUTHJ)ES authentica- 
tion). User programs rarely need to call it, or its associated routines 
keyjencryptsession, keyjgendes and key_setsecret. 

keyjlecryptsession takes a server netname remotename and a DES key 
deskey, and decrypts the key by using the the public key of the the server 
and the secret key associated with the effective UID of the calling process. 
It is the inverse of keyjencryptsession. 
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int 

keyjencryptsession (const char *reinotenaine, desj^lock *deskey) ; 

keyjencryptsession is a keyserver interface routine. It takes a server 
netname remotename and a DES key deskey, and encr3^s it using the pub- 
lic key of the the server and the secret key associated with the effective 
UID of the calling process. It is the inverse of keyjdecryptsession. This 
routine returns 0 if it succeeds, -1 if it fails. 

int 

J^^yjOPendes {des_block *deskey) ; 

keyjgendes is a keyserver interface routine. It is used to ask the 
keyserver for a secure conversation key. Choosing one at random is usu- 
ally not good enough, because the common ways of choosing random 
numbers, such as using the current time, are very easy to guess. 

int 

key_setsecret (const char *key); 

key_setsecret is a keyserver interface routine. It is used to set the key 
for the effective UID of the calling process, this routine returns 0 if it 
succeeds, -1 if it fails. 

int 

netnaitie2host (const char *name, char *host, const int hostlen) ; 

Convert from an operating-system independent netname name to a 
domain-specific hostname host, hostlen is the maximum size of host. 
Returns 1 if it succeeds, and 0 if it fails. Inverse of host2netname. 

int 

netnaxne2user (const char *naine, uidjt *ui<%>, gidjt *qi.6gf 
int *gidlenp, gid_t gidlist [NGROOPS] ) ; 

Convert from an operating-system independent netname to a domain- 
specific user ID. Returns 1 if it succeeds, and 0 if it fails. Inverse of 
user2netnaine. 

^uidp is set to the user's numerical ID associated with name. *gidp is set to 
the numerical ID of the group to which the user belongs, gidlist contains 
the numerical IDs of the other groups to which the user belongs, '''gidlenp 
is set to the number of valid group ID entries in gidlist. 

int 

user2netnaine (char naine[MAXNETNAMEIiEN+l] , const uid_t uid^ 
const char ^domain); 

Convert from a domain-specific username to an operating-system indepen- 
dent netname. Returns 1 if it succeeds, and 0 if it fails. Inverse of 
netnaine2user. 

SEE ALSO 

chkeyd), keyserv(lM), newkeyClM), rpc(3N), rpcjclnt_auth(3N). 
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NAME 

send, sendto, sendmsg - send a message from a socket 

SYNOPSIS 

♦include <sys/types.h> 
♦include <sys/socket . h> 

int send(s, xnsg, len, flags) 

int s; 

char '"msg; 

int len, flags; 

int sendto(s, msg, len, flags, to, tolen) 

int s; 

char *insg; 

int len, flags; 

struct sockaddr *to; 

int tolen; 

int sendxnsg(Sr msg, flags) 
int s; 

struct xnsghdr *insg; 
int flags; 

DESCRIPTION 

s is a socket created with socketON). sendO, sendtoO, and sendmsg () are 
used to transmit a message to another socket. sendO may be used only when 
the socket is in a connected state, while sendtoO and sendmsg () may be used at 
any time. 

The address of the target is given by to with tolen specifying its size. The length 
of the message is given by ten. If the message is too long to pass atomically 
through the underl3dng protocol, then the error EMSGSIZE is returned, and the 
message is not transmitted. 

No indication of failure to deliver is implicit in a send(). Return values of -1 
indicate some locally detected errors. 

If no buffer space is available at the socket to hold the message to be transmitted, 
then sendO normally blocks, unless the socket has been placed in non-blocking 
I/O mode (see fcntl(2)). The select () call may be used to determine when it 
is possible to send more data. 

The flags parameter is formed by ORing one or more of the following: 

MSGjOOB Send out-of-band data on sockets that support this notion. The 

underlying protocol must also support outof-band data. 
Currently, only SOCK_STREAM sockets created in the AF_INET 
address family support out-of-band data. 

MSG_pONTROUTE The SO_DONTROUTE option is turned on for the duration of the 
operation. It is used only by diagnostic or routing programs. 
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See recv(3N) for a description of the xnsghdr structure. 
RETURN VALUE 

These calls return the number of bytes sent, or -1 if an error occurred. 
ERRORS 



The calls fail if: 
EBADF 
ENOTSOCK 
EINVMi 



s is an invalid descriptor. 

s is a descriptor for a file, not a socket. 

tolen is not the size of a valid address for the specified 
address family. 

EINTR The operation was interrupted by delivery of a signal 

before any data could be buffered to be sent. 

EMSGSIZE The socket requires that message be sent atomically, and 

the message was too long. 

EWOOLDBLOCK The socket is marked non-blocking and the requested 

operation would block. 

ENC»4EM There was insufficient user memory available for the opera- 

tion to complete. 

ENOSR There were insufficient STREAMS resources available for the 

operation to complete. 

SEE ALSO 

connectON), fcntl(2), getsockopt(3N), recv(3N), socketOlSD, write(2). 
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NAME 

shutdown - shut down part of a full-duplex connection 

SYNOPSIS 

shutdown (s, how) 
int s, how; 

DESCRIPTION 

The shutdown ( ) call shuts down all or part of a full-duplex connection on the 
socket associated with s. If how is 0, then further receives will be disallowed. If 
how is 1, then further sends will be disallowed. If how is 2, then further sends 
and receives will be disallowed. 

RETURN VALUE 

A 0 is returned if the call succeeds, -1 if it fails. 

ERRORS 

The call succeeds unless: 

EBADF s is not a valid descriptor. 

ENOTSOCK s is a file, not a socket. 

ENOTOONN The specified socket is not connected. 

ENC»ffiM There was insufficient user memory available for the opera- 

tion to complete. 

ENOSR There were insufficient STREAMS resources available for the 

operation to complete. 

SEE ALSO 

connectON), socket(3N). 

NOTES 

The how values should be defined constants. 
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NAME 

socket - create an endpoint for communication 

SYNOPSIS 

♦include <sys/types . h> 
tinclude <sys/socket.h> 

int socket (domain, type, protocol) 
int domain, type, protocol; 

DESCRIPTION 

socket ( ) creates an endpoint for communication and returns a descriptor. 

The domain parameter specifies a communications domain within which commun- 
ication will take place; this selects the protocol family which should be used. The 
protocol family generally is the same as the address family for the addresses sup- 
plied in later operations on the socket. These families are defined in the include 
file /usr/include/sys/socket.h. There must be an entry in the netconfig(4) 
file for at least each protocol family and type required. If protocol has been 
specified, but no exact match for the tuplet family, ^yp®/ protocol is found, then 
the first entry containing the specified family and type with zero for protocol will 
l>e used. The currently understood formats are: 

PFjmix UNIX system internal protocols 

PF_INET ARPA Internet protocols 

The socket has the indicated type, which specifies the communication semantics. 
Currently defined types are: 

S0C3C_STREAM 

SOCKJDGRAM 

SOCK_RAW 

SOCKJSBQPACEaST 

SCCKRDM 

A SOCKJSTREAM type provides sequenced, reliable, two-way connection-based byte 
streams. An out-of-band data transmission mechanism may be supported. A 
SOCK_pGRAM socket supports datagrams (connectionless, imreliable messages of a 
fixed (typically small) maximum length). A SOCKJSEQPACKET socket may provide a 
sequenced, reliable, two-way connection-based data transmission path for 
datagrams of fixed maximum length; a consumer may he required to read an 
entire packet with each read system call. This facility is protocol specific, and 
presently not implemented for any protocol family. SOCKJRAW sockets provide 
access to internal network interfaces. The types SOCKRAW, which is available only 
to the super-user, and SOCKJRDH for which no implementation currently exists, are 
not described here. 

protocol specifies a particular protocol to be used with the socket. Normally only 
a single protocol exists to support a particular socket type within a given protocol 
family. However, multiple protocols may exist, in which case a particular proto- 
col must be specified in this manner. The protocol number to use is particular to 
the communication domain in which communication is to take place. If a proto- 
col is specified by the caller, then it will be packaged into a socket level option 
request and sent to the imderlying protocol layers. 
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Sockets of type S0C3C_STREAM are full-duplex byte streams, similar to pipes. A 
stream socket must be in a connected state before any data may be sent or 
received on it. A connection to another socket is created with a connect(3N) call. 
Once connected, data may be transferred using read(2) and write(2) calls or 
some variant of the send(3N) and recv(3N) calls. When a session has been com- 
pleted, a close(2) may be performed. Out-of-band data may also be transmitted 
as described on the send(3N) manual page and received as described on the 
recv(3N) manual page. 

The commimications protocols used to implement a S0CK_STREAM insure that data 
is not lost or duplicated. If a piece of data for which the peer protocol has buffer 
space cannot be successfully transmitted within a reasonable length of time, then 
the connection is considered broken and calls will indicate an error with -1 
returns and with ETIMEDOUT as the specific code in the global variable errno. 
The protocols optionally keep sockets warm by forcing transmissions roughly 
every minute in the absence of other activity. An error is then indicated if no 
response can be elicited on an otherwise idle connection for a extended period 
(for instance 5 minutes). A SIGPIPE signal is raised if a process sends on a broken 
stream; this causes naive processes, which do not handle the signal, to exit. 

SOCK_SEQPACKET sockets employ the same system calls as SOCKJSTREAM sockets. The 
only difference is that read calls will return only the amount of data requested, 
and any remaining in the arriving packet will be discarded. 

S0CK_DGRAM and SOOCJUW sockets allow datagrams to be sent to correspondents 
named in sendto calls. Datagrams are generally received with recvf ronv which 
returns the next datagram with its return address. 

An f cntl(2) call can be used to specify a process group to receive a SIGURG signal 
when the out-of-band data arrives. It may also enable non-blocking I/O and 
asynchronous notification of I/O events with SIGIO signals. 

The operation of sockets is controlled by socket level options. These options are 
defined in the file /usr/include/sys/socket.h. setsockopt(3N) and 
getsockopt(3N) are used to set and get options, respectively. 

RETURN VALUE 

A -1 is returned if an error occurs. Otherwise the return value is a descriptor 
referencing the socket. 

ERRORS 

The socket ( ) call fails if: 

EPROTONOSOPPORT The protocol type or the specified protocol is not supported 
within this domain. 

EMFILE The per-process descriptor table is full. 

EACCESS Permission to create a socket of the specified type and /or 

protocol is denied. 

ENOMEM Insufficient user memory is available. 
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ENOSR There were insufficient STREAMS resources available to 

complete the operation. 

SEE ALSO 

close(2), fcntl(2), ioctl(2), readil), write(2), acceptON), bind(3N), 

connectON), getsockname(3N), getsockoptON), listenON), recv(3N), 
send(3N), shutdown(3N), socketpair(3N). 
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NAME 

socketpair - create a pair of connected sockets 

SYNOPSIS 

♦include <sys/types . h> 
♦include <sys/socket.h> 

socketpair (d, type, protocol, sv) 
int d, type, protocol; 
int sv[2]; 

DESCRIPTION 

The socketpair ( ) library call creates an unnamed pair of connected sockets in 
the specified address family d, of the specified type , and using the optionally 
specified protocol. The descriptors used in referencing the new sockets are 
returned in sv[0] and sv[l]. The two sockets are indistinguishable. 

RETURN VALUE 

socketpair () returns a -1 on failure, otherwise it returns the number of the 
second file descriptor it creates. 

ERRORS 

The call succeeds unless: 

EMFILE Too many descriptors are in use by this process. 

EAFNOSDPPORT The specified address family is not supported on this 

machine. 

EPROTONOSUPPORT The specified protocol is not supported on this machine. 

EOPNOSUPPORT The specified protocol does not support creation of socket 

pairs. 

ENOMEM There was insufficient user memory for the operation to 

complete. 

ENOSR There were insufficient STREAMS resources for the operation 

to complete. 

SEE ALSO 

pipe(2), read(2), write(2) 

NOTES 

This call is currently implemented only for the AFJCJNIX address family. 
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NAME 

spray - scatter data in order to check the network 

SYNOPSIS 

♦include <rpcsvc/spray.h> 

DESCRIPTION 

The spray protocol sends packets to a given machine to test the speed and relia- 
bility of communications with that machine. 

The spray protocol is not a C function interface, per se, but can be accessed using 
the generic remote procedure calling interface clnt_call() [see 
rpcjclnt_calls(3N)]. The protocol sends a packet to the called host. The host 
acknowledges receipt of the packet. The protocol counts the number of ack- 
nowledgments and can return that count. 

The spray protocol currently supports the following procedures, which should be 
called in the order given: 

SPRAYPROCJCLEAR 

This procedure clears the counter. 

SPRAYPROC__SPRAY 

This procedure sends the packet. 

SPRAYPROCJGET 

This procedure returns the count and the amount of time since the last 
SPRAYPROCJCLEAR. 

The following XDR routines are available in librpcsvc: 

xdr_sprayarr 
xdr^spraycumul 

EXAMPLE 

The following code fragment demonstrates how the spray protocol is used: 
♦include <rpc/rpc.h> 
♦include <rpcsvc/spray.h> 



spraycuxnul spray_result; 
sprayarr sprayjdata; 

char buf [100]; /* aadDitrary data */ 

int loop = 1000; 

CLIENT *clnt; 

struct timeval tiineoutO « {0, 0}; 

struct timeval timeout25 = {25, 0); 

spray_jiata.sprayarr_len = (u_int)100; 
sprayjdata.sprayarrjval = buf; 

clnt « clnt_create("soinehost", SPRAYPROG, SPRAYVERS, "netpath") ; 
if (clnt — (CLIENT *)NULL) { 
/* handle this error */ 

} 
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if (clnt_call(clnt, SPRAYPROC_CLEAR, 

xdr^yoidr NULL, xdr_yoidr NULL, tinieout25)) { 
/* handle this error */ 

} 

i*hile (loop— > 0) { 

if (clnt_call(clnt, SPRAYPROC_SPRAY, 

xdr_sprayarr, &sprayjdata, xdr^yoid, NULL, timeoutO)) { 
/* handle this error */ 

} 

} 

if (clntjcalKclnt, SPRAYPR0C_C3ET, 

xdrjvoid, NULL, xdr__spraycunul, fisprayjcesult, tixneout25) ) { 
/* handle this error */ 

} 

print f ("Acknowledged %ld of 1000 packets in %d sees %d usecs\n", 
spray_result . counter, 
spray_result . clock . sec, 
spray_result . clock . usee) ; 

SEE ALSO 

rpcjclntjcallsON), spray(lM), sprayd(lM). 
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int tjaccept ( int fd, int resfd, struct tjcall *call) ; 
DESCRIPTION 

This function is issued by a transport user to accept a connect request, f d 
identifies the local transport endpoint where the connect indication arrived, 
resfd specifies the local transport endpoint where the connection is to be esta- 
blished, and call contains ii^ormation required by the transport provider to 
complete the connection, call points to a tjcall structure that contains the fol- 
lowing members: 

struct netbuf addr; 
struct netbuf qpt; 
struct net:bu£ udata; 
int sequence; 

netbuf is described in introO). In call, addr is the address of the caller, opt 
indicates any protocol-specific parameters associated with the connection, udata 
points to any user data to be returned to the caller, and sequence is the value 
returned by t__listen that imiquely associates the response with a previously 
received connect indication. 

A transport user may accept a connection on either the same, or on a different, 
local transport endpoint from the one on which the connect indication arrived. If 
the same endpoint is specified (i.e., resfd=fd), the connection can be accepted 
unless the following condition is true: The user has received other indications on 
that endpoint but has not responded to them (with tjaccept or t_snddis). For 
this condition, t__accept will fail and set t_errno to TBADF. 

If a different transport endpoint is specified (resfd! =fd), the endpoint must be 
bound to a protocol address and must be in the T^IDLE state [see 
tjgetstateON)] before the tjaccept is issued. 

For both types of endpoints, tjaccept will fail and set t_errno to TLOOK if there 
are indications (e.g., a connect or disconnect) waiting to be received on that end- 
point. 

The values of parameters specified by opt and the syntax of those values are pro- 
tocol specific. The udata argument enables the called transport user to send user 
data to the caller and the amount of user data must not exceed the limits sup- 
ported by the transport provider as returned in the connect field of the info 
argument of tjopen or t_getinfo. If the len [see netbuf in intro(3)l field of 
udata is zero, no data will be sent to the caller. 

On failure, t jerrno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint, or the user is illegally accepting a connection on 
the same transport endpoint on which the connect indication 
arrived. 
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The function was issued in the wrong sequence on the tran- 
sport endpoint referenced by fd, or the transport endpoint 
referred to by resfd is not in the T_IDLE state. 

The user does not have permission to accept a connection on 
the responding transport endpoint or use the specified 
options. 

The specified options were in an incorrect format or con- 
tained illegal information. 

The amount of user data specified was not within the 
bounds allowed by the transport provider. 

An invalid sequence number was specified. 

An asynchronous event has occurred on the transport end- 
point referenced by f d and requires immediate attention. 

This function is not supported by the imderlying transport 
provider. 

A system error has occurred during execution of this func- 
tion. 

SEE ALSO 

introO), t_connect(3N), t__getstate(3N), t_listen(3N), t__open(3N), 
t_rcvconnect(3N). 

UNIX System V Netzvork Programme/ s Guide. 
DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is 
returned and t errno is set to indicate the error. 



[TOUTSTATE] 

[TACCES] 

[TBADOPT] 

[TBADDATA] 

[TBADSEQ] 
[TLCX)K] 

[TNOTSUPPORT] 

[TSYSERR] 
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NAME 

t_alloc - allocate a libraiy structure 

SYNOPSIS 

♦include <tiuser.h> 

char *t_alloc(fd, structjtype, fields) 
int fd; 

int struct Jtype; 
int fields; 

DESCRIPTION 

The t_alloc function dynamically allocates memory for the various transport 
function argument structures as specified below. This function will allocate 
memory for the specified structure, and will also allocate memory for buffers 
referenced by the structure. 

The structure to allocate is specified by structjtype, and can be one of the fol- 
lowing: 

TJBIND struct t_bind 

TJCALL struct tjcall 

TjOPlMGMT struct tjoptmgmt 

T_piS struct tjdiscon 

TJCJNITDATA struct tjunitdata 
TJDDERROR struct tjuderr 

T_INFO struct t_info 

where each of these structures may subsequently be used as an argument to one 
or more transport functions. 

Each of the above structures, except T_INFO, contains at least one field of type 
struct netbuf . netJDuf is described in intro(3). For each field of this type, the 
user may specify that the buffer for that field should be allocated as well. The 
fields argument specifies this option, where the argument is the bitwise-OR of 
any of the following: 

T_ADDR The addr field of the t J^ind^ tjcall, tjunitdata, or tjuderr struc- 
tures. 

TJDPT The opt field of the tjpptmgmt, tjcall, tjunitdata, or tjuderr 
structures. 

TJCJDATA The udata field of the t_call, tjdiscon, or tjunitdata structures. 
T_ALL All relevant fields of the given structure. 

For each field specified in fields, t_jalloc will allocate memory for the buffer 
associated with the field, and initialize the buf pointer and itaxlen [see net±>uf in 
intro(3) for description of buf and xnaxlen] field accordingly. The length of the 
buffer allocated will be based on the same size information that is returned to the 
user on tjopen and tjgetinfo. Thus, fd must refer to the transport endpoint 
through which the newly allocated structure will be passed, so that the appropri- 
ate size information can be accessed. If the size value associated with any 



10/89 



Page 1 



t^alloc(3N) 



t_alloc(3N) 



specified field is -1 or -2 (see tjopen or t_getinfo), t alloc will be unable to 
determine the size of the buffer to allocate and willlail, setting tjerrno to 
TSYSERR and errno to EINVAL. For any field not specified in fields, buf will be 
set to NULL and itaxlen will be set to zero. 

Use of tjalloc to allocate structures will help ensure the compatibility of user 
programs with future releases of the transport interface. 

On failure, t_ermo may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport end- 

point. 

[TSYSERR] A system error has occurred during execution of this function. 
SEE ALSO 

introO), t_free(3hD, t_getinfo(3hD/ tjopen(3N). 
UNIX System V Network Programmer's Guide. 
DIAGNOSTICS 

On successful completion, t_alloc returns a pointer to the newly allocated struc- 
ture. On failure, NULL is returned. 
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NAME 

t_bincl - bind an address to a transport endpoint 

SYNOPSIS 

♦include <tiuser.h> 

int tjDind (fd, req, ret) 
int fd; 

struct tjDind *req; 
struct t_bind *ret; 

DESCRIPTION 

This function associates a protocol address with the transport endpoint specified 
by f d and activates that transport endpoint. In connection mode, the transport 
provider may begin accepting or requesting connections on the transport end- 
point. In connectionless mode, the transport user may send or receive data tinits 
through the transport endpoint. 

The req and ret arguments point to a t_bind structure containing the following 
members: 

struct netbuf addr; 
unsigned qlen; 

netbuf is described in introO). The addr field of the tjDind structure specifies 
a protocol address and the qlen field is used to indicate the maximtim number of 
outstanding connect indications. 

req is used to request that an address, represented by the netbuf structure, be 
bound to the given transport endpoint. len [see netbuf in introO); also for buf 
and maxlen] specifies the number of bytes in the address and buf points to the 
address buffer, inaxlen has no meaning for the req argument. On return, ret 
contains the address that the transport provider actually bound to the transport 
endpoint; this may be different from the address specified by the user in req. In 
ret, the user specifies maxlen, which is the maximum size of the address buffer, 
and buf, which points to the buffer where the address is to be placed. On return, 
len specifies the number of bytes in the boimd address and buf points to the 
bound address. If inaxlen is not large enough to hold the returned address, an 
error will result. 

If the requested address is not available, or if no address is specified in req (the 
len field of addr in req is zero) the transport provider may assign an appropri- 
ate address to be boimd, and will return that address in the addr field of ret. 
The user can compare the addresses in req and ret to determine whether the 
transport provider boimd the transport endpoint to a different address than that 
requested. 

req may be NULL if the user does not wish to specify an address to be bound. 
Here, the value of qlen is assimied to be zero, and the transport provider must 
assign an address to the transport endpoint. Similarly, ret may be NULL if the 
user does not care what address was bound by the provider and is not interested 
in the negotiated value of qlen. It is valid to set req and ret to NULL for the 
same call, in which case the provider chooses the address to bind to the transport 
endpoint and does not return that information to the user. 
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The qlen field has meaning only when initializing a connection-mode service. It 
specifies the number of outstanding connect indications the transport provider 
should support for the given transport endpoint. An outstanding connect indica- 
tion is one that has been passed to the transport user by the transport provider. 
A value of qlen greater than zero is only meaningful when issued by a passive 
transport user that expects other users to call it. The value of qlen will be nego- 
tiated by the transport provider and may be changed if the transport provider 
cannot support the specified number of outstanding connect indications. On 
return, the qlen field in ret will contain the negotiated value. 

This function allows more than one transport endpoint to be bound to the same 
protocol address (however, the transport provider must support this capability 
also), but it is not allowable to bind more than one protocol address to the same 
transport endpoint. If a user binds more than one transport endpoint to the same 
protocol address, only one endpoint can be used to listen for connect indications 
associated with that protocol address. In other words, only one t_bind for a 
given protocol address may specify a value of qlen greater than zero. In this 
way, the transport provider can identify which transport endpoint should be 
notified of an incoming connect indication. If a user attempts to bind a protocol 
address to a second transport endpoint with a value of qlen greater than zero, 
the transport provider will assign another address to be bound to that endpoint. 
If a user accepts a connection on the transport endpoint that is being used as the 
listening endpoint, the bound protocol address will be foimd to be busy for the 
duration of that connection. No other transport endpoints may be bound for 
listening while that initial listening endpoint is in the data transfer phase. This 
will prevent more than one transport endpoint bound to the same protocol 
address from accepting connect indications. 

On failure, t_ermo may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 



endpoint. 



[TOOTSTATE] 
[TBADADDR] 



The fimction was issued in the wrong sequence. 



The specified protocol address was in an incorrect format or 
contained illegal information. 



[TNOADDR] 
[TACCES] 



The transport provider could not allocate an address. 



The user does not have permission to use the specified 
address. 



[TBOFOVFLW] 



The number of bytes allowed for an incoming argument is 
not sufficient to store the value of that argument. The 
provider's state will change to T_IDIiE and the information 
to be returned in ret will be discarded. 



[TSYSERR] 



A system error has occurred during execution of this func- 
tion. 
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SEE ALSO 

intro(3), t_open(3N), t^c^tmgmtOND, t__unbind(3N). 
UNIX System V Network Programme/s Guide. 
DIAGNOSTICS 

tjDind returns 0 on success and -1 on failure and tjerrno is set to indicate the 
error. 



10/89 



Page 3 



t_cl08e(3N) 



t_,ciose(3N) 



NAME 

tjclose - close a transport endpoint 

SYNOPSIS 

♦include <tiuser.h> 

int t_jclose(fd) 
int fd; 

DESCRIPTION 

The tjclose function informs the transport provider that the user is finished 
with the transport endpoint specified by f d, and frees any local library resources 
associated with the endpoint. In addition, tjclose closes the file associated with 
the transport endpoint. 

t__close should be called from the T_UNBND state [see tjgetstate(3N)]. How- 
ever, this function does not check state information, so it may be called fi-om any 
state to close a transport endpoint. If this occurs, the local library resources asso- 
ciated with the endpoint will be freed automatically. In addition, close(2) will be 
issued for that file descriptor; the close will be abortive if no other process has 
that file open, and will break any transport connection that may be associated 
with that endpoint. 

On failure, tjerrno may be set to the following: 

[TBADF] The specified file descriptor does not refer to a transport endpoint. 
SEE ALSO 

t_getstate(3N), t_open(3N), t__\inbind(3N). 
UNIX System V Network Programmer's Guide, 
DIAGNOSTICS 

t_close returns 0 on success and ~1 on failure and t_ermo is set to indicate the 
error. 
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NAME 

t jconnect - establish a connection with another transport user 

SYNOPSIS 

♦include <tiuser.h> 

int t_connect (fd, sndcallr rcvcall) 
int fd; 

struct tjcall *sndcall; 
struct tjcall *rcvcall; 

DESCRIPTION 

This function enables a transport user to request a connection to the specified 
destination transport user, f d identifies the local transport endpoint where com- 
munication will be established, while sndcall and rcvcall point to a t_call 
structure that contains the following members: 

struct netbuf addr; 
struct netbuf opt; 
struct netbuf udata; 
int sequence; 

sndcall specifies information needed by the transport provider to establish a 
connection and rcvcall specifies information that is associated with the newly 
established connection. 

netbuf is described in intro(3). In sndcall, addr specifies the protocol address 
of the destination transport user, opt presents any protocol-specific information 
that might be needed by the transport provider, udata points to optional user 
data that may be passed to the destination transport user during connection 
establishment, and sequence has no meaning for this function. 

On return in rcvcall, addr returns the protocol address associated with the 
responding transport endpoint, opt presents any protocol-specific information 
associated with the connection, udata points to optional user data that may be 
returned by the destination transport user during connection establishment, and 
sequence has no meaning for this fimction. 

The opt argument implies no structure on the options that may be passed to the 
transport provider. The transport provider is free to specify the structure of any 
options passed to it. These options are specific to the imderlying protocol of the 
transport provider. The user may choose not to negotiate protocol options by 
setting the len field of opt to zero. In this case, the provider may use default 
options. 

The udata argument enables the caller to pass user data to the destination tran- 
sport user and receive user data from the destination user during connection 
establishment. However, the amount of user data must not exceed the limits sup- 
ported by the transport provider as returned in the connect field of the info 
argimient of tjopen(3N) or t_getinf o(3N). If the len [see netbuf in intro(3)] 
field of udata is zero in sndcall, no data will be sent to the destination transport 
user. 
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On return, the addr, opt, and udata fields of rcvcall will be updated to reflect 
values associated with the connection. Thus, the inaxlen [see netJDuf in intro(3)] 
field of each argument must be set before issuing this function to indicate the 
maximum size of the buffer for each. However, rcvcall may be NULL, in which 
case no information is given to the user on return from tjconnect. 

By default, t_connect executes in synchronous mode, and will wait for the desti- 
nation user's response before returning control to the local user. A successful 
return (i.e., return value of zero) indicates that the requested connection has been 
established. However, if OJJDELAY or OJJONBLOCK is set (via t_ppen or fcntl), 
t_connect executes in asynchronous mode. In this case, the call will not wait for 
the remote user's response, but will return control immediately to the local user 
and return -1 with tjerrno set to TNODATA to indicate that the connection has not 
yet been established. In this way, the function simply initiates the connection 
establishment procedure by sending a connect request to the destination transport 
user. 

On failure, t_ermo 
[TBADF] 

[TOUTSTATE] 
[TNODATA] 

[TBADADDR] 
[TBADOPT] 
[TBADDATA] 
[TACCES] 
[TBUFOVFLW] 



[TIOOK] 

[TNOTSOPPORT] 

[TSYSERR] 



may be set to one of the following: 

The specified file descriptor does not refer to a transport 
endpoint. 

The function was issued in the wrong sequence. 

0_NDELAY or 0_NONBLOCK was set, so the function success- 
fully initiated the connection establishment procedure, but 
did not wait for a response from the remote user. 

The specified protocol address was in an incorrect format or 
contained illegal information. 

The specified protocol options were in an incorrect format or 
contained illegal information. 

The amount of user data specified was not within the 
bounds allowed by the transport provider. 

The user does not have permission to use the specified 
address or options. 

The number of bytes allocated for an incoming argument is 
not sufficient to store the value of that argument. If exe- 
cuted in synchronous mode, the provider's state, as seen by 
the user, changes to T^DATAXFER, and the connect indication 
information to be returned in rcvcall is discarded. 

An as5nichronous event has occurred on this transport end- 
point and requires immediate attention. 

This function is not supported by the underljdng transport 
provider. 

A system error has occurred during execution of this func- 
tion. 
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SEE ALSO 

intro(3), t_accept(3N), t_getinf o(3N), t_listen(3N), t_open(3N), 
t_optmgmt(3N), t_rcvconnect(3N). 
UNIX System V Netzvork Programmer's Guide, 
DIAGNOSTICS 

tjconnect returns 0 on success and -1 on feilure and tjermo is set to indicate 
the error. 
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NAME 

t jBrror - produce error message 

SYNOPSIS 

♦include <tiuser.h> 

void t_jerror(ernnsg) 
char *ernnsg; 
extern int tjerrno; 
extern char *t_errlist [] ; 
extern int t_nerr; 

DESCRIPTION 

tjerror produces a message on the standard error output which describes the 
last error encountered during a call to a transport function. The argument string 
errmsg is a user-supplied error message that gives context to the error. 

t__error prints the user-supplied error message followed by a colon and the stan- 
dard transport function error message for the current value contained in t_errno. 
If t_ermo is TSYSERR, tjerror will also print the standard error message for the 
current value contained in errno [see intro(2)]. 

t_errlist is the array of message strings, to allow user message formatting. 
t_ermo can be used as an index into this array to retrieve the error message 
string (without a terminating newline). tjnerr is the maximum index value for 
the tjerrlist array. 

t_ermo is set when an error occurs and is not cleared on subsequent successful 
calls. 

EXAMPLE 

If a tjconnect fimction fails on transport endpoint 162 because a bad address 
was given, the following call might follow the failure: 

t_error("t_connect foiled on fd2"); 

The diagnostic message would print as: 

t__connect failed on fd2: Incorrect transport address format 

where "t_connect failed on fd2'' tells the user which function failed on which 
transport endpoint, and "Incorrect transport address format" identifies the 
specific error that occurred. 

SEE ALSO 

UNIX System V Network Programmer's Guide, 



10/89 



Page 1 



tJree(3N) t_freG(3N) 



NAME 

t_f ree - free a library structure 

SYNOPSIS 

♦include <tiuser.h> 

int t_f ree (ptr, structjtype) 

char *ptr; 

int structjtype; 

DESCRIPTION 

The t_f ree function frees memory previously allocated by t_allcx;. This fimc- 
tion will free memory for the specified structure, and vsdll also free memory for 
buffers referenced by the structure. 

ptr points to one of the six structure types described for t_alloc, and 
struct_type identifies the type of that structure, which can be one of the follow- 
ing: 

TJBIND struct tjbind 

TjCALL struct tjcall 

TJOPTMGMT struct tjopt:mgmt 

TJ)IS struct t_discon 

TJ[JNITDATA struct t__unitdata 
TJCJDERROR Struct t_uderr 

T_INEX) struct t_info 

where each of these structures is used as an argument to one or more transport 
functions. 

t_free will check the addr, opt, and udata fields of the given structure (as 
appropriate), and free the buffers pointed to by the buf field of the netbuf [see 
intrc<3)] structure. If buf is NULL, t_f ree will not attempt to free memory. 
After all buffers are freed, t_f ree will free the memory associated with the struc- 
ture pointed to by ptr. 

Undefined results will occur if ptr or any of the buf pointers points to a block of 
memory that was not previously allocated by t_alloc. 

On failure, t_errno may be set to the following: 

[TSYSERR] A system error has occurred during execution of this function. 

SEE ALSO 

intro(3), t_alloc(3N). 
UNIX System V Network Programme/ s Guide, 
DIAGNOSTICS 

t_free returns 0 on success and -1 on feilure and tjerrno is set to indicate the 
error. 
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NAME 

tjgetinf o - get protocol-specific service information 

SYNOPSIS 

♦include <tiuser.h> 

int t_getinfo(fd, info) 
int fd; 

struct t_info *info; 
DESCRIPTION 

This function returns the current characteristics of the underlying transport proto- 
col associated with file descriptor f d. The info structure is used to return the 
same information returned by t_cpen. This function enables a transport user to 
access this information during any phase of commimication. 

This argument points to a t_info structure, which contains the following 
members: 

long addr; /* max size of the transport protocol address */ 

long options; /* max number of bytes of protocol-specific options */ 

long tsdu; /* max size of a transport service data tmit (TSDU) */ 

long etsdu; /* max size of an expedited transport service data unit (ETSDU) */ 

long connect; /* max amount of data allowed on connection establishment functions */ 

long discon; /* max amoimt of data allowed on t_snddis and t_rcvdis functions */ 

long sexvtype; /* service type supported by the transport provider */ 

The values of the fields have the following meanings: 

addr A value greater than or equal to zero indicates the maximum size 

of a transport protocol address; a value of -1 specifies that there 
is no limit on the address size; and a value of -2 specifies that the 
transport provider does not provide user access to transport pro- 
tocol addresses. 

options A value greater than or equal to zero indicates the maximum 
number of bytes of protocol-specific options supported by the pro- 
vider; a value of -1 specifies that there is no limit on the option 
size; and a value of -2 specifies that the transport provider does 
not support user-settable options. 

tsdu A value greater than zero specifies the maximum size of a tran- 

sport service data unit (TSDU); a value of zero specifies that the 
transport provider does not support the concept of TSDU, although 
it does support the sending of a data stream with no logical boun- 
daries preserved across a connection; a value of -1 specifies that 
there is no limit on the size of a TSDU; and a value of -2 specifies 
that the transfer of normal data is not supported by the transport 
provider. 

etsdu A value greater than zero specifies the maximum size of an 

expedited transport service data unit (ETSDU); a value of zero 
specifies that the transport provider does not support the concept 
of ETSDU, although it does support the sending of an expedited 
data stream with no logical boundaries preserved across a 
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connection; a value of -1 specifies that there is no limit on the size 
of an ETSDU; and a value of ~2 specifies that the transfer of 
expedited data is not supported by the transport provider. 

A value greater than or equal to zero specifies the maximum 
amoimt of data that may be associated with connection establish- 
ment functions; a value of -1 specifies that there is no limit on the 
amount of data sent during connection establishment; and a value 
of -2 specifies that the transport provider does not allow data to 
be sent with connection establishment functions. 

A value greater than or equal to zero specifies the maximimi 
amount of data that may be associated with the tjsnddis and 
t_rcvdis functions; a value of -1 specifies that there is no limit 
on the amount of data sent with these abortive release fimctions; 
and a value of -2 specifies that the transport provider does not 
allow data to be sent with the abortive release functions. 

servtype This field specifies the service type supported by the transport 
provider, as described below. 

If a transport user is concerned with protocol independence, the above sizes may 
be accessed to determine how large the buffers must be to hold each piece of 
information. Alternatively, the t_alloc function may be used to allocate these 
buffers. An error will result if a transport user exceeds the allowed data size on 
any function. The value of each field may change as a result of option negotia- 
tion, and tjgetinf o enables a user to retrieve the current characteristics. 

The servtype field of info may specify one of the following values on return: 

TjCX>TS The transport provider supports a connection-mode service but 

does not support the optional orderly release facility. 

TjCOTSjDRD The transport provider supports a connection-mode service with 
the optional oiderly release facility. 

TjCLTS The transport provider supports a connectionless-mode service. 

For this service type, tjppen will return -2 for etsdu, connect, 
and discon. 

On failure, tjerrno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport end- 

point. 

[TSYSERR] A system error has occurred during execution of this function. 

SEE ALSO 

t_open(3N). 

UNIX System V Nettvork Programmers Guide. 
DIAGNOSTICS 

tjgetinfo returns 0 on success and -1 on failure and tjerrno is set to indicate 
the error. 
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NAME 

t jgetstate - get the current state 

SYNOPSIS 

tinclude <tiuser.h> 

int tjget state (fd) 
int fd; 

DESCRIPTION 

The tjgetstate function returns the current state of the provider associated with 
the transport endpoint specified by f d. 

On failure, tjerrno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport end- 

point. 

[TSTATECHNG] The transport provider is undergoing a state change. 

[TSYSERR] A system error has occurred during execution of this fimc- 

tion. 

SEE ALSO 

tjopenON). 

UNIX System V Netzvork Programmers Guide. 
DIAGNOSTICS 

t jgetstate returns the current state on successful completion and -1 on failure 
and t jerrno is set to indicate the error. The current state may be one of the fol- 
lowing: 

TJJNBND unbound 
T_IDLE idle 

TJDUTOON outgoing connection pending 
T_INOON incoming connection pending 

TJDATAXFER data transfer 

TjOlTTOEL outgoing orderly release (waiting for an orderly release indica- 
tion) 

T_INREL incoming orderly release (waiting for an orderly release request) 

If the provider is undergoing a state transition when tjgetstate is called, the 
fimction will fail. 
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NAME 



t_listen - listen for a connect request 



SYNOPSIS 



♦include <tiuser.h> 



int t_listen(fd, call) 
int fd; 

struct t call *call; 



DESCRIPTION 



This function listens for a connect request from a calling transport user, fd 
identifies the local transport endpoint where connect indications arrive, and on 
return, call contains information describing the connect indication, call points 
to a tjcall structure, which contains the following members: 

struct netbuf addr; 
truct netJDuf opt; 
struct netbuf udata; 
int sequence; 

netbuf is described in intro(3). In call, addr returns the protocol address of 
the calling transport user, opt returns protocol-specific parameters associated 
with the connect request, udata returns any user data sent by the caller on the 
connect request, and sequence is a number that uniquely identifies the returned 
connect indication. The value of sequence enables the user to listen for multiple 
connect indications before responding to any of them. 

Since this function returns values for the addr, opt, and udata fields of call, the 
maxlen [see netbuf in intro(3)] field of each must be set before issuing 
t_listen to indicate the maximimi size of the buffer for each. 

By default, t_listen executes in synchronous mode and waits for a connect indi- 
cation to arrive before returning to the user. However, if OJIDELAY or 
0_NONBLOCK is set (via t_cpen or fcntl), t_listen executes asynchronously, 
reducing to a poll for existing connect indications. If none are available, it 
returns -1 and sets tjerrno to TNODATA. 

On failure, t jerrno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 



endpoint. 



[TBUFOVFLW] 



The number of bytes allocated for an incoming argument is 
not sufficient to store the value of that argument. The 
provider's state, as seen by the user, changes to T_INCON, 
and the connect indication information to be returned in 
call is discarded. 



[TNODATA] 



0_NDELAY or 0_NONBLOCK was set, but no connect indica- 
tions had been queued. 



[TLOOK] 



An asynchronous event has occurred on this transport end- 
point and requires immediate attention. 
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[TNOTSUPPORT] 



This function is not supported by the underlying transport 
provider. 



[TSYSERR] 



A system error has occurred during execution of this func- 
tion. 



CAVEATS 



If a user issues t_listen in synchronous mode on a transport endpoint that was 
not bound for listening (i.e., qlen was zero on tjDind), the call will wait forever 
because no connect indications will arrive on that endpoint. 

SEE ALSO 

introO), t_accept(3N), t J>ind(3N), t_connect(3N), t_open(3N), 
t_rcvconnect(3N). 

UNIX System V Network Programme/ s Guide. 
DIAGNOSTICS 

t_listen returns 0 on success and -1 on failure and tjerrno is set to indicate 
the error. 
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NAME 

t_look - look at the current event on a transport endpoint 

SYNOPSIS 

♦include <tiuser.h> 

int t_look(fd) 
int fd; 

DESCRIPTION 

This function returns the current event on the transport endpoint specified by f d. 
This function enables a transport provider to notify a transport user of an asyn- 
chronous event when the user is issmng functions in s5mchronous mode. Certain 
events require immediate notification of the user and are indicated by a specific 
error, TLOOK, on the current or next fimction to be executed. 

This function also enables a transport user to poll a transport endpoint periodi- 
cally for asynchronous events. 

On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport end- 

point. 

[TSYSERR] A system error has occurred during execution of this function. 

SEE ALSO 

t_open(3N). 

UNIX System V Netzoork Programmer's Guide. 
DIAGNOSTICS 

Upon success, t_look returns a value that indicates which of the allowable events 



returned: 




TJLISTEN 


connection indication received 


T_CONNECT 


connect confirmation received 


T_DATA 


normal data received 


T_EXDATA 


expedited data received 


TJ)ISCONNECT 


disconnect received 


TJJDERR 


datagram error indication 


TJDRDREL 


orderly release indication 



On failure, -1 is returned and t ermo is set to indicate the error. 
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NAME 

tjopen - establish a transport endpoint 

SYNOPSIS 

♦include <tiuser.h> 

tinclude <fcntl.h> 

int tjopen (char path, int oflag, struct t_info ♦info) ; 
DESCRIPTION 

tjppen must be called as the first step in the initialization of a transport end- 
point. This function establishes a transport endpoint by opening a UNIX file that 
identifies a particular transport provider (i.e., transport protocol) and returning a 
file descriptor that identifies that endpoint. For example, opening the file 
/dev/iso_cots identifies an OSI connection-oriented transport layer protocol as 
the transport provider. 

path points to the path name of the file to open, and of lag identifies any open 
flags [as in ppen(2)]. of lag may be constructed from pJIDELAY or 0_NONBLCX:k 
OR-ed with 0_RDWR. These flags are defined in the header file <fcntl.h>. 
tjopen returns a file descriptor that will be used by all subsequent functions to 
identify the particular local transport endpoint. 

This function also returns various default characteristics of the underlying tran- 
sport protocol by setting fields in the t_inf o structure. This argument points to 
a t_inf o which contains the following members: 

long addr; /* max size of the transport protocol address */ 

long options; /* max number of bytes of protocol-spedfic options */ 

long tsdu; /* max size of a transport service data tmit (TSDU) */ 

long etsdu; /* max size of an expedited transport service data unit (ETSDU) */ 

long connect; /* max amount of data allowed on connection establishment functions */ 

long discon; /* max amoimt of data allowed on t__snddis and t__rcvdis functions */ 

long servtype; /* service type supported by the transport provider */ 

The values of the fields have the following meanings: 

addr A value greater than or equal to zero indicates the maximum size 

of a transport protocol address; a value of -1 specifies that there 
is no limit on the address size; and a value of -2 specifies that the 
transport provider does not provide user access to transport pro- 
tocol addresses. 

options A value greater than or equal to zero indicates the maximum 
number of bytes of protocol-specific options supported by the pro- 
vider; a value of -1 specifies that there is no limit on the option 
size; and a value of -2 specifies that the transport provider does 
not support user-settable options. 

tsdu A value greater than zero specifies the maximum size of a tran- 

sport service data unit (TSDU); a value of zero specifies that the 
transport provider does not support the concept of TSDU, although 
it does support the sending of a data stream with no logical boim- 
daries preserved across a connection; a value of -1 specifies that 
there is no limit on the size of a TSDU; and a value of -2 specifies 
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that the transfer of normal data is not supported by the transport 
provider. 

A value greater than zero specifies the maximum size of an 
expedited transport service data unit (ETSDU); a value of zero 
specifies that the transport provider does not support the concept 
of ETSDU, although it does support the sending of an expedited 
data stream with no logical boundaries preserved across a connec- 
tion; a value of -1 specifies that there is no limit on the size of an 
ETSDU; and a value of -2 specifies that the transfer of expedited 
data is not supported by the transport provider. 

A value greater than or equal to zero specifies the maximum 
amoimt of data that may be associated with connection establish- 
ment functions; a value of -1 specifies that there is no limit on the 
amoimt of data sent during connection establishment; and a value 
of -2 specifies that the transport provider does not allow data to 
be sent with connection establishment fimctions. 

A value greater than or equal to zero specifies the maximimi 
amount of data that may be associated with the t_snddis and 
t_rcvdis functions; a value of -1 specifies that there is no limit 
on the amount of data sent with these abortive release functions; 
and a value of -2 specifies that the transport provider does not 
allow data to be sent with the abortive release functions. 

servtype This field specifies the service type supported by the transport 
provider, as described below. 

If a transport user is concerned with protocol independence, the above sizes may 
be accessed to determine how large the buffers must be to hold each piece of 
information. Alternatively, the t_alloc function may be used to allocate these 
buffers. An error will result if a transport user exceeds the allowed data size on 
any function. 

The servtype field of info may specify one of the following values on return: 

TjCOTS The transport provider supports a connection-mode service but 

does not support the optional orderly release facility. 

TjCOTSjDRD The transport provider supports a connection-mode service with 
the optional orderly release facility. 

TjCLTS The transport provider supports a connectionless-mode service. 

For this service type, t_ppen will return -2 for etsdu, connect, 
and discon. 

A single transport endpoint may support only one of the above services at one 
time. 

If info is set to uu, by the transport user, no protocol information is returned by 
t_open. 
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On failure, t_errno may be set to the following: 

[TSYSERR] A system error has occurred during execution of this func- 

tion. 

[TBADFLAG] An invalid flag is specified. 

DIAGNOSTICS 

tjopen returns a valid file descriptor on success and -1 on failure and t_errno 
is set to indicate the error. 

NOTES 

If t_open is used on a non-TLI-conforming STREAMS device, unpredictable events 
may occur. 

SEE ALSO 

open(2). 

UNIX System V Network Programmer's Guide. 
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NAME 

tjpptxngitit - manage options for a transport endpoint 

SYNOPSIS 

♦include <tiuser.h> 

int tjoptmgmt (int fd^ struct tjoptmgmt *req, struct tjoptingmt *ret) ; 
DESCRIPTION 

The tjpptmgmt function enables a transport user to retrieve, verify, or negotiate 
protocol options with the transport provider, f d identifies a bound transport 
endpoint. 

The req and ret arguments point to a t jpptmgmt structure containing the fol- 
lowing members: 

struct netJ^uf opt; 
long flags; 

The opt field identifies protocol options and the flags field is used to specify the 
action to take with those options. 

The options are represented by a netJ^uf [see intro(3); also for len, buf, and 
maxlen] structure in a manner similar to the address in tjDind. req is used to 
request a specific action of the provider and to send options to the provider, len 
specifies the number of bytes in the options, buf points to the options buffer, and 
xnaxlen has no meaning for the req argument. The transport provider may 
return options and flag values to the user through ret. For ret, maxlen specifies 
the maximum size of the options buffer and buf points to the buffer where the 
options are to be placed. On return, len specifies the number of bytes of options 
returned, maxlen has no meaning for the req argument, but must be set in the 
ret argument to specify the maximum number of bytes the options buffer can 
hold. The actual structure and content of the options is imposed by the transport 
provider. 

The flags field of req can specify one of the following actions: 

TJJEGOTIATE This action enables the user to negotiate the values of the options 
specified in req with the transport provider. The provider will 
evaluate the requested options and negotiate the values, return- 
ing the negotiated values through ret. 

TjCHECK This action enables the user to verify whether the options 

specified in req are supported by the transport provider. On 
return, the flags field of ret will have either T__SUCCESS or 
T__FAILURE set to indicate to the user whether the options are 
supported. These flags are only meaningful for the TjCHECK 
request. 

T_DEFAULT This action enables a user to retrieve the default options sup- 
ported by the transport provider into the opt field of ret. In 
req, the len field of opt must be zero and the buf field may be 
NULL. 
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If issued as part of the connectionless-mode service, tjoptimgrnt may block due to 
flow control constraints. The fimction will not complete until the transport pro- 
vider has processed all previously sent data imits. 

On failure, t_ermo may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint. 

[TOUTSTATE] The function was issued in the wrong sequence. 

[TAOCES] The user does not have permission to negotiate the 

specified options. 

[TBADOPT] The specified protocol options were in an incorrect format 

or contained illegal information. 

[TBADFLAG] An invalid fiag was specified. 

[TBDFOVFLW] The number of bytes allowed for an incoming argtmient is 

not sufficient to store the value of that argument. The 
information to be returned in ret will be discarded. 

[TSYSERR] A system error has occurred during execution of this func- 

tion. 

SEE ALSO 

intro(3), tjgetinf o(3N), tjopen(3N). 
UNIX System V Network Programmers Guide, 
DIAGNOSTICS 

t__optmgmt returns 0 on success and -1 on failure and tjerrno is set to indicate 
the error. 
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NAME 

t_rcv - receive data or expedited data sent over a connection 
SYNOPSIS 

int t_rcv (int £d, char "'buf, lonsigned nbytes, int '•'flags) ; 
DESCRIPTION 

This function receives either normal or expedited data, fd identifies the local 
transport endpoint through which data will arrive, buf points to a receive buffer 
where user data will be placed, and nbytes specifies the size of the receive 
buffer, flags may be set on return from tjrcv and specifies optional fiags as 
described below. 

By default, tjccv operates in synchronous mode and will wait for data to arrive 
if none is currently available. However, if OJNDELAY or OJIONBLOCK is set (via 
tjppen or fcntl), t_rcv will execute in as3aichronous mode and will fail if no 
data is available. (See TNODATA below.) 

On return from the call, if T_MORE is set in flags, this indicates that there is more 
data and the current transport service data unit (TSDU) or expedited transport ser- 
vice data imit (ETSDU) must be received in multiple tjrcv calls. Each tjrcv with 
the T_MORE flag set indicates that another t_rcv must follow to get more data for 
the current TSDU. The end of the TSDU is identified by the return of a t_rcv call 
with the T_MDRE flag not set. If the transport provider does not support the con- 
cept of a TSDU as indicated in the info argument on return from tjopen or 
t_getinf o, the T__MORE flag is not meaningful and should be ignored. 

On return, the data returned is expedited data if T_EXPEDITED is set in flags. If 
the number of bytes of expedited data exceeds nbytes, tjccv will set 
T_EXPEDITED and T_MORE on return from the initial call. Subsequent calls to 
retrieve the remaining ETSDU will have T_EXPEDITED set on return. The end of 
the ETSDU is identified by the return of a t_rcv call with the T_MORE flag not set. 

If expedited data arrives after part of a TSDU has been retrieved, receipt of the 
remainder of the TSDU will be suspended until the ETSDU has been processed. 
Only after the full ETSDU has been retrieved (T_MORE not set) will the remainder 
of the TSDU be available to the user. 

On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint. 

[TNODATA] 0_NDELAY or 0_N0NBLCX:K was set, but no data is currently 

available from the transport provider. 

[TIXX)K] An asynchronous event has occurred on this transport end- 

point and requires immediate attention. 

[TNOTSUPPORT] This function is not supported by the underlying transport 
provider. 

[TSYSERR] A system error has occurred during execution of this fimc- 

tion. 
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SEE ALSO 

tjopenON), t_snd(3N). 
UNIX System V Network Programme/s Guide, 
DIAGNOSTICS 

On successful completion, t_rcv returns the number of bytes received, and it 
returns ~1 on failtire and t errno is set to indicate the error. 



Page 2 



10/89 



tjcvconnect(3N) 



t_rcvconnect(3N) 



NAME 

t_rcvconnect - receive the confirmation ft-om a connect request 

SYNOPSIS 

♦include <tiuser.h> 

int tjrcvconnect (int fd, struct tjcall *call) ; 
DESCRIPTION 

This function enables a calling transport user to determine the status of a previ- 
ously sent connect request and is used in conjunction with tjconnect to establish 
a connection in asynchronous mode. The connection will be established on suc- 
cessful completion of this function. 

fd identifies the local transport endpoint where communication will be esta- 
blished, and call contains information associated with the newly established con- 
nection, call points to a tjcall structure which contains the following 
members: 

struct netbuf addr; 
struct netbuf opt; 
struct netbuf udata; 
int sequence; 

netbuf is described in introO). In call, addr returns the protocol address 
associated with the responding transport endpoint, opt presents any protocol- 
specific information associated with the connection, udata points to optional user 
data that may be returned by the destination transport user during connection 
establishment, and sequence has no meaning for this fimction. 

The maxlen [see netbuf in intro(3)] field of each argument must be set before 
issuing this function to indicate the maximtim size of the buffer for each. How- 
ever, call may be NULL, in which case no information is given to the user on 
return from t_rcvconnect. By default, tjrcvconnect executes in sjmchronous 
mode and waits for the connection to be established before returning. On return, 
the addr, opt, and udata fields reflect values associated with the connection. 

If OJJDELAY or 0»_NONBLCX2K is set (via t_ppen or f cntl), tjrcvconnect executes 
in as3mchronous mode, and reduces to a poll for existing connect confirmations. 
If none are available, t jccvconnect fails and returns immediately without wait- 
ing for the connection to be established. (See TNODATA below.) tjrcvconnect 
must be re-issued at a later time to complete the connection establishment phase 
and retrieve the information returned in call. 

On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint. , 

[TBUPOVFLW] The number of bytes allocated for an incoming argument is 

not sufficient to store the value of that argument and the 
connect information to be returned in call will be dis- 
carded. The provider's state, as seen by the user, will be 
changed to DATAXFER. 
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[TNODATA] qjIDEIAY or OJWONBIOCK was set, but a connect 

confirmation has not yet arrived. 

[TLOOK] An asynchronous event has occurred on this transport con- 

nection and requires immediate attention. 

[TNOTSUPPC^T] This function is not supported by the underlying transport 
provider. 

[TSYSERR] A system error has occurred during execution of this func- 

tion. 

SEE ALSO 

introO), t_accept(3N)/ tjDind(3N), t_connect(3N), t_listen(3N), 
tjopen(3ND. 

UNIX System V Network Programmers Guide. 
DIAGNOSTICS 

tjccvconnect returns 0 on success and -1 on failure and tjerrno is set to indi- 
cate the error. 
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NAME 

t_rcvdis - retrieve information from disconnect 

SYNOPSIS 

♦include <tiuser.h> 

t_rcvdis (int fd, struct t_discon *discori) ; 
DESCRIPTION 

This function is used to identify the cause of a (disconnect, and to retrieve any 
user data sent with the disconnect, fd identifies the local transport endpoint 
where the connection existed, and discon points to a tjdiscon structure contain- 
ing the following members: 

struct netibuf udata; 
int reason; 
int sequence; 

netJDuf is described in introO). reason specifies the reason for the disconnect 
through a protocol-dependent reason code, udata identifies any user data that 
was sent with the disconnect, and sequence may identify an outstanding connect 
indication with which the disconnect is associated, sequence is only meaningful 
when t_rcvdis is issued by a passive transport user who has executed one or 
more t_listen functions and is processing the resulting connect indications. If a 
disconnect indication occurs, sequence can be used to identify which of the out- 
standing connect indications is associated with the disconnect. 

If a user does not care if there is incoming data and does not need to know the 
value of reason or sequence, discon may be NULL and any user data associated 
with the disconnect will be discarded. However, if a user has retrieved more 
than one outstanding connect indication (via t_listen) and discon is NULL, the 
user will be unable to identify which connect indication the disconnect is associ- 
ated with. 

On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does hot refer to a transport 

endpoint. 

[TNODIS] No disconnect indication currently exists on the specified 

transport endpoint. 

[TBUFOVFLW] The nimiber of bytes allocated for incoming data is not 

sufficient to store the data. The provider's state, as seen by 
the user, will change to T_IDLE, and the disconnect indica- 
tion information to be returned in discon will be dis- 
carded. 

[TNOTSUPPORT] This function is not supported by the underlying transport 
provider. 

[TSYSERR] A system error has occurred during execution of this fimc- 

tion. 
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SEE ALSO 

introO), tjconnectON), t_listen(3N), t_ppen(3N), t_8nddi8(3N). 
UNIX System V Network Programme/ s Guide, 
DIAGNOSTICS 

t_rcvdis returns 0 on success and -1 on failure and tjerrno is set to indicate 
the error. 



Page 2 



10/89 



tjcvrel(3N) 



tjcvrel(3N) 



NAME 

t_rcvrel - acknowledge receipt of an orderly release indication 

SYNOPSIS 

♦include <tiuser.h> 

tjrcvrel (int fd); 
DESCRIPTION 

This function is used to acknowledge receipt of an orderly release indication. £d 
identifies the local transport endpoint where the connection exists. After receipt 
of this indication, the user should not attempt to receive more data because such 
an attempt will block forever. However, the user may continue to send data over 
the connection if t_sndrel has not been issued by the user. 

This function is an optional service of the transport provider, and is only sup- 
ported if the transport provider returned service type TjOOTSjDRD on t_ppen or 
tjgetinfo. 

On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint. 

[TNOBEL] No orderly release indication currently exists on the 

specified transport endpoint. 

[TIOOK] An asynchronous event has occurred on this transport end- 

point and requires immediate attention. 

[TNOTSUPPORT] This function is not supported by the underlying transport 
provider. 

[TSYSERR] A system error has occurred during execution of this fimc- 

tion. 

SEE ALSO 

tjopenON), t_sndrel(3N). 
UNIX System V Network Programmer's Guide. 
DIAGNOSTICS 

tjrcvrel returns 0 on success and -1 on failure t_errno is set to indicate the 
error. 
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NAME 

t_rcvudata - receive a data unit 

SYNOPSIS 

♦include <tiuser.h> 

int t_rcvudata (int fd, struct tjunitdata *unitdata, int *flags); 
DESCRIPTION 

This function is used in connectionless mode to receive a data unit from another 
transport user, f d identifies the local transport endpoint through which data will 
be received, unitdata holds information associated with the received data imit, 
and flags is set on return to indicate that the complete data imit was not 
received, unitdata points to a tjunitdata structure containing the following 
members: 

struct netbuf addr; 
struct netJDuf opt; 
struct netbuf udata; 

The xnaxlen [see netJ^uf in intro(3)l field of addr, opt, and udata must be set 
before issuing this function to indicate the maximum size of the buffer for each. 

On return from this call, addr specifies the protocol address of the sending user, 
opt identifies protocol-specific options that were associated with this data imit, 
and udata specifies the user data that was received. 

By default, t_rcvudata operates in synchronous mode and will wait for a data 
unit to arrive if none is currently available. However, if 0_NDEIAY or 
0_NONBLOCK is set (via tjopen or f cntl), t_rcvudata will execute in asynchro- 
nous mode and will fail if no data units are available. 

If the buffer defined in the udata field of unitdata is not large enough to hold 
the current data imit, the buffer will be filled and T_MORE will be set in flags on 
return to indicate that another t_rcvudata should be issued to retrieve the rest 
of the data unit. Subsequent t_rcvudata call(s) will return zero for the length of 
the address and options until the full data unit has been received. 

On failure, tjerrno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint. 

[TNODATA] 0_NDELAY or OJIONBLOCK was set, but no data units are 

currently available from the transport provider. 

[TBUPOVFLW] The number of bytes allocated for the incoming protocol 

address or options is not sufficient to store the information. 
The unit data information to be returned in unitdata will 
be discarded. 

[TLOOK] An asynchronous event has occurred on this transport end- 

point and requires immediate attention. 

[TNOTSUPPORT] This function is not supported by the underlying transport 
provider. 
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[TSYSERR] A system error has occtirred dtiring execution of this func- 

tion. 

SEE ALSO 

intro(3), t_rcvuderr(3hD, t_sndudata(3N). 
UNIX System V Netzvork Programmer's Guide, 
DIAGNOSTICS 

t_rcvudata returns 0 on successful completion and -1 on failure and t_errno is 
set to indicate the error. 
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NAME 

t_rcvuderr - receive a unit data error indication 

SYNOPSIS 

♦include <tiuser.h> 

int t_rcvuderr (int fd^ struct tjuderr *uderr); 
DESCRIPTION 

This function is used in connectionless mode to receive inforn\ation concerning an 
error on a previously sent data unit, and should be issued only after a unit data 
error indication. It informs the transport user that a data unit with a specific des- 
tination address and protocol options produced an error, f d identifies the local 
transport endpoint through which the error report will be received, and uderr 
points to a tjuderr structure containing the following members: 

struct netbuf addr; 
struct netJauf opt; 
long error; 

netbuf is described in intro(3). The xnaxlen [see netbuf in intro(3)] field of 
addr and qpt must be set before issuing this function to indicate the maximum 
size of the buffer for each. 

On return from this call, the addr structure specifies the destination protocol 
address of the erroneous data unit, the opt structure identifies protocol-specific 
options that were associated with the data unit, and error specifies a protocol- 
dependent error code. 

If the user does not care to identify the data unit that produced an error, uderr 
may be set to NULL and t__rcvuderr will simply clear the error indication 
without reporting any information to the user. 

On failure, tjerrno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport end- 

point. 

[TNOODERR] No unit data error indication currently exists on the specified 

transport endpoint. 

[TBUFOVFLW] The number of bytes allocated for the incoming protocol 
address or options is not sufficient to store the information. 
The unit data error information to be returned in uderr will 
be discarded. 

[TNOTSUPPORT] This fimction is not supported by the underlying transport 
provider. 

ITSYSERR] A system error has occurred during execution of this fimc- 

tion. 

SEE ALSO 

intro(3), t_rcvudata(3N), tjsndudata(3N). 
UNIX System V Network Programmer's Guide. 
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DIAGNOSTICS 

t_rcvuderr returns 0 on successful completion and -1 on failure and tjerrno is 
set to indicate the error. 
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NAME 

t_snd - send data or expedited data over a connection 

SYNOPSIS 

finclude <tiuser.h> 

int t_snd (int £d, char *bu£, unsigned nbytes, int flags) ; 
DESCRIPTION 

This function is used to send either normal or expedited data, fd identifies the 
local transport endpoint over which data should be sent, buf points to the user 
data, nbytes specifies the number of bytes of user data to be sent, and flags 
specifies any optional flags described below. 

By default, t_snd operates in synchronous mode and may wait if flow control 
restrictions prevent the data from being accepted by the local transport provider 
at the time the call is made. However, if 0_NDELAY or qjWNBLOCK is set (via 
tjopen or fcntl), t_snd will execute in asynchronous mode, and will fail 
immediately if there are flow control restrictions. 

Even when there are no flow control restrictions, t_snd will wait if STREAMS 
internal resources are not available, regardless of the state of p_NDEIiAY or 
OJIONBLOCK. 

On successful completion, t_snd returns the number of bytes accepted by the 
transport provider. Normally this will equal the number of bytes specified in 
nbytes. However, if pJIDELAY or OJJONBLOCK is set, it is possible that only part 
of the data will be accepted by the transport provider. In this case, t_snd will set 
T_MORE for the data that was sent (see below) and will return a value less than 
nbytes. If nbytes is zero and sending of zero bytes is not supported by the 
underlying transport provider, tjsndO will return -1 with tjerrno set to TBAD- 
DATA. A return value of zero indicates that the request to send a zero-length data 
message was sent to the provider. 

If T_EXPEDITED is set in flags, the data will be sent as expedited data, and will 
be subject to the interpretations of the transport provider. 

If TJ«)RE is set in flags, or is set as described above, an indication is sent to the 
transport provider that the transport service data unit (TSDU) or expedited tran- 
sport service data unit (ETSDU) is being sent through multiple t_snd calls. Each 
t_snd with the T_MORE flag set indicates that another t_snd will follow with 
more data for the current TSDU. The end of the TSDU (or ETSDU) is identified by a 
t_snd call with the T_MORE flag not set. Use of T_MORE enables a user to break 
up large logical data units without losing the boimdaries of those units at the 
other end of the connection. The flag implies nothing about how the data is 
packaged for transfer below the transport interface. If the transport provider 
does not support the concept of a TSDU as indicated in the info argmnent on 
return from tjppen or t_getinfo, the T_MORE flag is not meaningful and should 
be ignored. 

The size of each TSDU or ETSDU must not exceed the limits of the transport pro- 
vider as returned by t_open or t_getinf o. If the size is exceeded, a TSYSERR 
with system error EPROTO will occur. However, the tjsnd may not fail because 
EPROTO errors may not be reported immediately. In this case, a subsequent call 
that accesses the transport endpoint will fail with the associated TSYSERR. 
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If t_8nd is issued from the T_IDLE state, the provider may silently discard the 
data. If t_snd is issued from any state other than TJDATAXFER, T_INREL or 
T__IDLE, the provider will generate a TSYSERR with system error EPROTO (which 
may be reported in the manner described above). 

On foilure, tjermo may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpbint. 

[TFLOW] 0_NDELAY or p_NONBLOCK was set, but the flow control 

mechanism prevented the transport provider from accept- 
ing data at this time. 

[TNOTSUPPORT] This function is not supported by the underlying transport 
provider. 

[TSYSERR] A system error [see intro(2)] has been detected during exe- 

cution of this function. 

[TBADDATA] nbytes is zero and sending zero bytes is not supported by 

the transport provider. 

SEE ALSO 

t_ppen(3N), t_rcv(3N). 
UNIX System V Network Programmer's Guide, 
DIAGNOSTICS 

On successful completion, tjsnd returns the number of bytes accepted by the 
transport provider, and it returns -1 on failure and tjermo is set to indicate the 
error. 
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NAME 

t_snddis - send user-initiated disconnect request 

SYNOPSIS 

♦include <tiuser.h> 

int t_snddis (int fd, struct tjcall *call) : 
DESCRIPTION 

This function is used to initiate an abortive release on an already established con- 
nection or to reject a connect request, f d identifies the local transport endpoint of 
the connection, and call specifies information associated with the abortive 
release, call points to a t_call structure that contains the following members: 

struct netJ^uf addr; 
struct netbuf opt; 
struct netbuf udata; 
int sequence; 

netbuf is described in introO). The values in call have different semantics, 
depending on the context of the call to t_snddis. When rejecting a connect 
request, call must be non-NULL and contain a valid value of sequence to iden- 
tify imiquely the rejected connect indication to the transport provider. The addr 
and opt fields of call are ignored. In all other cases, call need only be used 
when data is being sent with the disconnect request. The addr, opt, and 
sequence fields of the t_call structure are ignored. If the user does not wish to 
send data to the remote user, the value of call may be NULL. 

udata specifies the user data to be sent to the remote user. The amount of user 
data must not exceed the limits supported by the transport provider as returned 
in the discon field of the info argument of tjppen or tjgetinfo. If the len 
field of udata is zero, no data will be sent to the remote user. 

On failure, t__errno may be set to one of the following: 



[TBADF] 



The specified file descriptor does not refer to a transport 
endpoint. 



[TOUTSTATE] 



The function was issued in the wrong sequence. The tran- 
sport provider's outgoing queue may be flushed, so data 
may be lost. 



[TBADDATA] 



The amount of user data specified was not within the 
bounds allowed by the transport provider. The transport 
provider's outgoing queue will be flushed, so data may be 
lost. 



[TBADSEQ] 



An invalid sequence number was specified, or a NULL call 
structure was specified when rejecting a connect request. 
The transport provider's outgoing queue will be flushed, so 
data may be lost. 



[TLOOK] 



An asynchronous event has occurred on this transport end- 
point and requires immediate attention. 
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[TNOTSUPPORT] This function is not supported by the underl5dng transport 
provider. 

[TSYSERR] A system error has occurred during execution of this func- 

tion. 

SEE ALSO 

introO), tjconnectON), tjgetinfoOlSD/ t_listen(3N), t_ppen(3N). 
UNIX System V Netzvork Programme/ s Guide. 
DIAGNOSTICS 

t_snddis returns 0 on success and -1 on failure and tjerrno is set to indicate 
the error. 
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t_sndrel - initiate an orderly release 

SYNOPSIS 

♦include <tiuser.h> 

int t_sndrel (int fd); 
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DESCRIPTION 

This function is used to initiate an orderly release of a transport connection and 
indicates to the transport provider that the transport user has no more data to 
send, fd identifies the local transport endpoint where the connection exists. 
After issuing t_sndrel, the user may not send any more data over the connec- 
tion. However, a user may continue to receive data if an orderly release indica- 
tion has not been received. 

This function is an optional service of the transport provider, and is only sup- 
ported if the transport provider returned service type TjCOTSjORD on tjppen or 
tjgetinfo. 

If t_sndrel is issued from an invalid state, the provider will generate an EPROTO 
protocol error; however, this error may not occur until a subsequent reference to 
the transport endpoint. 

On failure, tjerrno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint. 

[TFLOW] qjTOELAY or 0_NONBLOCK was set, but the flow control 

mechanism prevented the transport provider from accept- 
ing the function at this time. 

[TNOTSUPPORT] This function is not supported by the underlying transport 
provider. 

[TSYSERR] A system error has occurred during execution of this fimc- 

tion. 

SEE ALSO 

t_open(3N), t_rcvrel(3N). 
UNIX System V Network Programmer's Guide. 
DIAGNOSTICS 

t_sndrel returns 0 on success and -1 on failure and t_errno is set to indicate 
the error. 
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NAME 

t_sndudata - send a data unit 

SYNOPSIS 

♦include <tiuser.h> 

int t_sndudata (int fd^ struct tjunitdata *unitdata) ; 
DESCRIPTION 

This function is used in connectionless mode to send a data unit to another tran- 
sport user, f d identifies the local transport endpoint through which data will be 
sent, and lanitdata points to a tjunitdata structure containing the following 
members: 

struct netbuf addr; 
struct netbuf opt; 
struct net:buf udata; 

netbuf is described in intro(3). In unitdata, addr specifies the protocol 
address of the destination user, opt identifies protocol-specific options that the 
user wants associated with this request, and udata specifies the user data to be 
sent. The user may choose not to specify what protocol options are associated 
with the transfer by setting the len field of opt to zero. In this case, the provider 
may use default options. 

If the len field of udata is zero, and the sending of zero bytes is not supported 
by the underlying transport provider, t_sndudata will return -1 with t_ermo 
set to TBADDATA. 

By default, t_sndudata operates in synchronous mode and may wait if flow con- 
trol restrictions prevent the data from being accepted by the local transport pro- 
vider at the time the call is made. However, if p_NDELAY or O^NONBLOCK is set 
(via t_open or f cntl), tjsndudata will execute in asynchronous mode and will 
fail imder such conditions. 

If t_sndudata is issued from an invalid state, or if the amount of data specified 
in udata exceeds the TSDU size as returned in the tsdu field of the info argu- 
ment of tjopen or tjgetinfo, the provider will generate an EPROTO protocol 
error. (See TSYSERR below.) If the state is invalid, this error may not occur imtil 
a subsequent reference is made to the transport endpoint. 

On failure, t jerrno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport end- 

point. 

[TFLOW] OJIDELAY or 0JK)NBLCX3C was set, but the flow control 

mechanism prevented the transport provider from accepting 
data at this time. 

[TNOTSUPPORT] This fimction is not supported by the underlying transport 
provider. 

[TSYSERR] A system error has occurred during execution of this func- 

tion. 
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[TBADDATA] nbytes is zero and sending zero bytes is not supported by 

the transport provider. 

SEE ALSO 

introO), tjrcvudataON), tjccvuderrON). 
UNIX System V Network Programmer's Guide, 
DIAGNOSTICS 

t^sndudata returns 0 on successful completion and -1 on failtire t_errno is set 
to indicate the error. 
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NAME 

t jsync - synchronize transport library 

SYNOPSIS 

♦include <tiuser.h> 

int t__sync (int fd); 
DESCRIPTION 

For the transport endpoint specified by f d^ t_8ync synchronizes the data struc- 
tures managed by the transport library with information from the underlying 
transport provider. In doing so, it can convert a raw file descriptor [obtained via 
ppen(2), dup(2), or as a result of a f ork(2) and exec(2)] to an initialized transport 
endpoint, assuming that file descriptor referenced a transport provider. This 
function also allows two cooperating processes to synchronize their interaction 
with a transport provider. 

For example, if a process forks a new process and issues an exec, the new pro- 
cess must issue a t_sync to build the private library data structure associated 
with a transport endpoint and to synchronize the data structure with the relevant 
provider information. 

It is important to remember that the transport provider treats all users of a tran- 
sport endpoint as a single user. If multiple processes are using the same end- 
point, they should coordinate their activities so as not to violate the state of the 
provider. t_sync returns the current state of the provider to the user, thereby 
enabling the user to verify the state before taking fiirther action. This coordina- 
tion is only valid among cooperating processes; it is possible that a process or an 
incoming event could change the provider's state after a t_sync is issued. 

If the provider is undergoing a state transition when t_sync is called, the func- 
tion will fail. 

On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint. 

[TSTATECHNG] The transport provider is undergoing a state change. 

[TSYSERR] A system error has occurred during execution of this func- 

tion. 

SEE ALSO 

dup(2), exec(2), fork(2), ppen(2). 
UNIX System V Netzvork Programme/ s Guide. 
DIAGNOSTICS 

t_sync returns the state of the transport provider on successful completion and 
-1 on failure and t_errno is set to indicate the error. The state returned may be 
one of the following: 

T UNBND unbound 
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T_IDLE 

TJOUTCON 

T_INCON 

TJDATAXFER 

TJOOTREL 

T INREL 



idle 

outgoing connection pending 
incoming connection pending 
data transfer 

outgoing orderly release (waiting for an orderly release indi- 
cation) 

incoming orderly release (waiting for an orderly release 
request) 
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NAME 

t junbind - disable a transport endpoint 

SYNOPSIS 

♦include <tiuser.h> 

int t junbind (int fd) ; 
DESCRIPTION 

The tjiinbind function disables the transport endpoint specified by f d which was 
previously bound by t_bind(3N). On completion of this call, no further data or 
events destined for this transport endpoint will be accepted by the transport pro- 
vider. 

On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport end- 

point. 

[TOUTSTATE] The function was issued in the wrong sequence. 

[TLOOK] An asynchronous event has occurred on this transport endpoint. 

[TSYSERR] A system error has occurred during execution of this function. 

SEE ALSO 

tJ>ind(3N). 

UNIX System V Network Programme/ s Guide. 
DIAGNOSTICS 

t junbind returns 0 on success and -1 on failure and tjerrno is set to indicate 
the error. 
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NAME 

xdr - library routines for external data representation 
DESCRIPTION 

XDR routines allow C programmers to describe arbitrary data structures in a 
machine-independent fashion. Data for remote procedure calls (RPC) are 
transmitted using these routines. 

Index to Routines 

The following table lists XDR routines and the manual reference pages on which 
they are described: 

XDR Routine Manual Reference Page 



xdr_array 
xdrjxx)! 
xdrjaytes 
xdrjchar 
xdrjdestroy 
xdrjdouble 
xdr_enum 
xdr_float 
xdr_free 
xdr_getpos 
xdr_inline 
xdr_int 
xdr__long 
xdrjopaque 
xdr_pointer 
xdr_reference 
xdr_setpos 
xdr_short 
xdr_string 
xdrjujchar 
xdrju_lbng 
xdr_u_short 
xdrjunion 
xdr_vector 
xdr_yoid 
xdrjwrapstring 
xdxinemjcreate 
xdrrecjcreate 
xdrrecjeof 
xdrstdio create 



xdrjconplexON) 
xdr_siirple(3N) 
xdrjcoxrplexON) 
xdr__sin|>le(3N) 
xdrjcreate(3N) 
xdrjSirapleON) 
xdrjsiinpleON) 
xdr_sjLnple(3N) 
xdrjsinple(3N) 
xdrjadmin(3N) 
xdr_admin(3N) 
xdr_sinple(3N) 
xdrjsijnple(3N) 
xdrjcoitplex(3N) 
xdrjconplex(3N) 
xdr_coirplex(3N) 
xdr_jadinin(3N) 
xdr_siirple(3N) 
xdrJCOlnplex(3^D 
xdrjsixrple(3N) 
xdr_sinple(3N) 
xdr_sinple(3N) 
xdrjcoinplex{3N) 
xdrjcoirplex(3N) 
xdrjsinple(3N) 
xdr_ccMnplex(3hD 
xdrjcreate(3N) 
xdrjcreate(3N) 
xdrjadmin(3N) 
xdr create(3N) 



SEE ALSO 

xdr_adinin(3N), xdrjcomplex(3N), xdr_create(3N), xdr_sin|>le(3N), rpc(3N). 
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NAME 

xdr^admin: xdr^getpos, xdr_inline, xdrrecjeof , xdrjsetpos - library rou- 
tines for external data representation 

DESCRIPTION 

XDR library routines allow C programmers to describe arbitrary data structures 
in a machine-independent fashion. Protocols such as remote procedure calls 
(RPC) use these routines to describe the format of the data. 

These routines deal specifically with the management of the XDR stream. 

Routines 

See rpc(3N) for the definition of the XDR data structure. 

♦include <rpc/xdr.h> 

u_int 

xdrjgetpos (const XDR *xdrs) ; 

A macro that invokes the get-position routine associated with the XDR 
stream, xdrs. The routine returns an unsigned integer, which indicates the 
position of the XDR byte stream. A desirable feature of XDR streams is 
that simple arithmetic works with this number, although the XDR stream 
instances need not guarantee this. Therefore, applications written for por- 
tability should not depend on this feature. 

long * 

xdr_inline (XDR *xdrs; const int len) ; 

A macro that invokes the in-line routine associated with the XDR stream, 
xdrs. The routine returns a pointer to a contiguous piece of the stream's 
buffer; len is the byte length of the desired buffer. Note: pointer is cast to 
long *. 

Warning: xdr_inline may return NULL (0) if it cannot allocate a contigu- 
ous piece of a buffer. Therefore the behavior may vary among stream 
instances; it exists for the sake of efficiency, and applications written for 
portability should not depend on this feature. 

booljt 

xdrrecjeof (XDR *xdrs) ; 

This routine can be invoked only on streams created by xdrrecjcreate. 
After consuming the rest of the current record in the stream, this routine 
returns 1 if the stream has no more input, 0 otherwise. 

booljt 

xdrjsetpos (XDR *xdrs, const u_int pos) ; 

A macro that invokes the set position routine associated with the XDR 
stream xdrs. The parameter pos is a position value obtained from 
xdrjgetpos. This routine returns 1 if the XDR stream was repositioned, 
and 0 otherwise. 

Warning: it is difficult to reposition some t5^pes of XDR streams, so this 
routine may fail with one type of stream and succeed with another. 
Therefore, applications written for portability should not depend on this 
feature. 
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SEE ALSO 

rpc(3N), xdrjconplexON), xdrjcreateON), xdr_siii|>le(3N). 
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NAME 

xdrjoomplex: xdrjirray; xdrjDytes, xdrjopaque, xdrjpointer, 
xdr_re£erence, xdrjstring, xdrjunion, xdrjvector, xdrjcrcqpstring - 
library routines for external data representation 

DESCRIPTION 

XDR library routines allow C programmers to describe complex data structures in 
a machine-independent fashion. Protocols such as remote procedure calls (RFC) 
use these routines to describe the format of the data. These routines are the XDR 
library routines for complex data structures. They require the creation of XDR 
stream [see xdr_create(3N)]. 

Routines 

See rpc(3N) for the definition of the XDR data structure. 

♦include <i:pc/xdr.h> 

booljt 

xdr_aj:ray(XDR *xdrSr caddr^t *arrpr u_int *8izep, 
const u_int maxsize, const u_int elsize, 
const xdrprocjt elproc) ; 

xdr_array translates between variable-length arrays and their correspond- 
ing external representations. The parameter arrp is the address of the 
pointer to the array, while sizep is the address of the element count of the 
array; this element count cannot exceed maxsize. The parameter elsize is 
the sizeof each of the arra5^s elements, and elproc is an XDR routine that 
translates between the array elements' C form and their external represen- 
tation. This routine returns 1 if it succeeds, 0 otherwise. 

booljt 

xdrJ^es(XDR *xdrs, char **sp, u_int *sizep, 
const u__int maxsize); 

xdr_bytes translates between counted byte strings and their external 
representations. The parameter sp is the address of the string pointer. 
The length of the string is located at address sizep; strings cannot be 
longer than maxsize. This routine returns 1 if it succeeds, 0 otherwise. 

booljt 

xdrjopaque (XDR *xdrs, caddr_t qp, const u_int cnt) ; 

xdr_opaque translates between fixed size opaque data and its external 
representation. The parameter cp is the address of the opaque object, and 
cnt is its size in bytes. This routine returns 1 if it succeeds, 0 otherwise. 

booljt 

xdrjpointer(XDR *xdrs, char **6bjpp, u_int objsize, 
const xdrprocjt xdrobj); 

Like xdr_reference except that it serializes NULL pointers, whereas 
xdr_re£erence does not. Thus, xdrjpointer can represent recursive 
data structures, such as binary trees or linked lists. 
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bool_t 

xdrjreference (XDR ^xdrs, caddr__t *pp, u_int size, 
cx>nst xdrproc_t proc); 

xdrjreference provides pointer chasing within structures. The parame- 
ter pp is the address of the pointer; size is the sizeof the structure that 
*pp points to; and proc is an XDR procedure that translates the structure 
between its C form and its external representation. This routine returns 1 
if it succeeds, 0 otherwise. 

Warning: this routine does not understand NULL pointers. Use 
xdrjpointer instead. 

bool_t 

xdr jstring (XDR *xdrs, char **sp, const u_int naxsize) ; 

xdrjBtring translates between C strings and their corresponding external 
representations. Strings cannot be longer than maxsize. Note: sp is the 
address of the string's pointer. This routine returns 1 if it succeeds, 0 oth- 
erwise. 

bool_t 

xdr jonion (XDR *xdrs, enuin_t *dscnp, char *unp, 
const struct xdrjdiscrim ^choices, 

const bool_t (*defaultarm) (const XDR *, const char *, 
const int)); 

xdrjunion translates between a discriminated C union and its 
corresponding external representation. It first translates the discriminant 
of the union located at dscmp. This discriminant is always an enumjt. 
Next the union located at unp is translated. The parameter choices is a 
pointer to an array of xdr__discrim structures. Each structure contains an 
ordered pair of [mlue, proc]. If the union's discriminant is equal to the 
associated value, then the proc is called to translate the union. The end of 
the xdrjdiscrim structure array is denoted by a routine of value NULL. If 
the discriminant is not foimd in the choices array, then the defaultarm pro- 
cedure is called (if it is not NULL). Returns 1 if it succeeds, 0 otherwise. 

boolj: 

xdr_vector(XDR *xdrs, char *arrpr const u_int size, 
const u_int elsize, const xdrproc_t elproc) ; 

xdrjvector translates between fixed-length arrays and their correspond- 
ing external representations. The parameter arrp is the address of the 
pointer to the array, while size is is the element count of the array. The 
parameter ehize is the sizeof each of the array's elements, and elproc is an 
XDR routine that translates between the array elements' C form and their 
external representation. This routine returns 1 if it succeeds, 0 otherwise. 
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booljt 

xdrjMrapstring(XDR *xdrs, char **sp) ; 

A routine that calls xdr_string(jcirs^ sp, maxuint) ; where maxuint is the 
maximum value of an unsigned integer. 

Many routines, such as xdr_array, xdr_pointer and xdrjvector take a 
fimction pointer of type xdrprocjt, which takes two arguments. 
xdr_string, one of the most frequently used routines, requires three 
argimients, while xdrjwrapstring only requires two. For these routines, 
xdrjwrapstring is desirable. This routine returns 1 if it succeeds, 0 oth- 
erwise. 

SEE ALSO 

rpc(3N), xdr_admin(3N), xdr_create(3^D, xdr_siinple(3hD. 
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NAME 

xdrjcreate: xdrjdiestroy, xdbnneinjcreate, xdrrecjcreate, 
xdrstdiojcreate - library routines for external data representation stream crea- 
tion 

DESCRIPTION 

XDR library routines allow C programmers to describe arbitrary data structures 
in a machine-independent fashion. Protocols such as remote procedure calls 
(RFC) use these routines to describe the format of the data. 

These routines deal with the creation of XDR streams. XDR streams have to be 
created before any data can be translated into XDR format. 

Routines 

See rpc(3N) for the definition of the XDE, CLIENT, and SVCXPRT data structures. 

♦include <rpc/xdr.h> 

void 

xdrjdestroy(XDR *xdrs) ; 

A macro that invokes the destroy routine associated with the XDR stream, 
xdrs. Destruction usually involves freeing private data structures associ- 
ated with the stream. Using xdrs after invoking xdrjdestroy is 
undefined. 

void 

xdrmemjcreate (XDR *xdrs, const caddr_t addr, 
const u_int size, const enum xdr_c^ op) ; 

This routine initializes the XDR stream object pointed to by xdrs. The 
stream's data is written to, or read from, a chunk of memory at location 
addr whose length is no more than size bytes long. The op determines the 
direction of the XDR stream (either XDR_ENCQDE, XDRJ)ECODE, or 
XDR_FREE). 

void 

xdrrec_jcreate (XDR *xdrs, const u_int sendsz, 

const u_int recvsz, const caddrjt handle, 

const int (*readit) (const void *, char const int) , 

const int (*writeit) (const void *^ const char *, const int) ) ; 

This routine initializes the XDR stream object pointed to by xdrs. The 
stream's data is written to a buffer of size sendsz; a value of 0 indicates the 
system should use a suitable default. The stream's data is read from a 
buffer of size recvsz; it too can be set to a suitable default by passing- a 0 
value. When a stream's output buffer is full, writeit is called. Similarly, 
when a stream's input buffer is empty, readit is called. The behavior of 
these two routines is similar to the system calls read and write [see 
read(2) and write(2), respectively], except that handle (CLIENT, or 
SVCXPRT) is passed to the former routines as the first parameter instead of 
a file descriptor. Note: the XDR stream's op field must be set by the caller. 
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Warning: this XDR stream implements an intermediate record stream. 
Therefore there are additional bytes in the stream to provide record boun- 
dary information. 

void 

xdrstdiojcxeate (XDR *xdrs, FILE *fiie, const eniim xdrjop op) ; 

This routine initializes the XDR stream object pointed to by xdrs. The 
XDR stream data is written to, or read from, the standard I/O stream file. 
The parameter op determines the direction of the XDR stream (either 
XDRJENCODE, XDRJ)EOODE, or XDR_FREE). 

Warning: the destroy routine associated with such XDR streams calls 
f flush on the^k stream, but never f close [see fclose(3S)]. 



f closeOS), read(2), rpc(3N), write(2), xdr_admin(3^D, xdr_coirplex(3N), 
xdrjsiirple(3N). 



SEE ALSO 
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NAME 

xdr_sixnple: xdrjbool, xdr_char, xdrjdouble, xdr_enunv xdr_f loat, 
xdr_f ree, xdr_int, xdr_long, xdr_short, xdr jujchar, xdrju_long, 
xdrju_short, xidrjvoid - library routines for external data representation 

DESCRIPTION 

XDR library routines allow C programmers to describe simple data structures in a 
machine-independent fashion. Protocols such as remote procedure calls (RPC) 
use these routines to describe the format of the data. 

These routines require the creation of XDR streams [see xdrjcreateON)]. 

Routines 

See rpc(3N) for the definition of the XDR data structure. 

♦include <rpc/xdr.h> 

booljt 

xdrJbooKXDR *xdrs, bool_t *bp) ; 

xdrjxxjl translates between booleans (C integers) and their external 
representations. When encoding data, this filter produces values of either 
1 or 0. This routine returns 1 if it succeeds, 0 otherwise. 

booljt 

xdrjchar(XDR *xdrs, char *cp); 

xdr_char translates between C characters and their external representa- 
tions. This routine returns 1 if it succeeds, 0 otherwise. Note: encoded 
characters are not packed, and occupy 4 bytes each. For arrays of charac- 
ters, it is worthwhile to consider xdr_bytes, xdr_ppaque or xdr_string 
[see xdrjbytes, xdr_opaque and xdr_string in xdr_coraplex(3^D]. 

booljt 

xdrjdoiable (XDR *xdrs, double *dp) ; 

xdrjciouble translates between C double precision numbers and their 
external representations. This routine returns 1 if it succeeds, 0 otherwise. 

booljt 

xdrjenum(XDR *xdrs, enifln_t *ep) ; 

xdrj&num translates between C enums (actually integers) and their external 
representations. This routine returns 1 if it succeeds, 0 otherwise. 

booljt 

xdr_f loat (XDR *xdrs, float *fp); 

xdr_float translates between C floats and their external representa- 
tions. This routine returns 1 if it succeeds, 0 otherwise. 

void 

xdr_f ree (xdrprocjt proc, char *db jp) ; 

Generic freeing routine. The first argument is the XDR routine for the 
object being freed. The second argument is a pointer to the object itself. 
Note: the pointer passed to this routine is not freed, but what it points to 
is freed (recursively). 
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boolj: 

xdr_int(XDR *x6r8, int *ip) ; 

xdrjLnt translates between C integers and their external representations. 
This routine returns 1 if it succeeds, 0 otherwise. 

booljt 

xdrJ.ong(XDR *xdrs, long *lp) ; 

xdr_long translates between C long integers and their external represen- 
tations. This routine returns 1 if it succeeds, 0 otherwise. 

booljt 

xdr jshort (XDR *xdrs, short *sp); 

xdrjshort translates between C short integers and their external 
representations. This routine returns 1 if it succeeds, 0 otherwise. 

bool_t 

xdrju_char(XDR *xdrs, char *ucp) ; 

xdrjLijchar translates between unsigned C characters and their external 
representations. This routine returns 1 if it succeeds, 0 otherwise. 

booljt 

xdrju_long(XDR *xdrs, unsigned long *ulp); 

xdrju_long translates between C unsigned long integers and their 
external representations. This routine returns 1 if it succeeds, 0 otherwise. 

boolj: 

xdrju_short (XDR *xdrs, unsigned short *usp) ; 

xdrju_short translates between C unsigned short integers and their 
external representations. This routine returns 1 if it succeeds, 0 otherwise. 

booljt 

xdr_yoid(void) / 

This routine always returns 1. It may be passed to RPC routines that 
require a function parameter, where nothing is to be done. 

SEE ALSO 

rpc(3N), xdr_admin(3N)/ xdrjcoirplex(3N), xdrjcreateOhD. 
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NAME 

ypclntr ypjgetjdefaultjdtomain, ypjDind, ypjunbind, ypjnatch, 
yp_first, ypjnextr yp_all, ypjorder^ yp^master, yperr_string, 
ypprotjerr - YP client interface 

SYNOPSIS 

♦include <rpcsvc/ypclnt . h> 
♦include <rpcsvc/yp_prot .h> 

DESCRIPTION 

This package of functions provides an interface to the YP network lookup service. 
The package can be loaded from the standard library, /usr/lib/libnsl . {so, a}. 
Refer to ypfiles(4) and ypserv(lM) for an overview of the YP name services, 
including the definitions of map and domain, and a description of the various 
servers, databases, and commands that comprise the YP name service. 

All input parameters names begin with in. Output parameters begin with out. 
Output parameters of type char ** should be addresses of uninitialized charac- 
ter pointers. Memory is allocated by the YP client package using mallcxjO), and 
may be freed if the user code has no continuing need for it. For each outkey and 
outval, two extra bytes of memory are allocated at the end that contain NEWLINE 
and NULL, respectively, but these two bytes are not reflected in outkeylen or out- 
vallen, indomain and inmap strings must be non-NULL and NULL-terminated. 
String parameters which are accompanied by a count parameter may not be 
NULL, but may point to NULL strings, with the count parameter indicating this. 
Counted strings need not be NULL-terminated. 

All functions in this package of type int return 0 if they succeed, and a failure 
code (YBBBRjcxxx) otherwise. Failure codes are described under DL\GNOSTICS 
below. 

Routines 

yp_bind (indomain) ; 
char * indomain/ 

To use the YP name services, the client process must be bound to a YP 
server that serves the appropriate domain using yp_bind ( ) . Binding 
need not be done explicitly by user code; this is done automatically when- 
ever a YP lookup function is called. yp_bind( ) can be called directly for 
processes that make use of a backup strategy (for example, a local file) in 
cases when YP services are not available. 

void 

ypjunbind (indomain) 
char * indomain; 

Each binding allocates (uses up) one client process socket descriptor; each 
bound domain costs one socket descriptor. However, multiple requests to 
the same domain use that same descriptor, ypjunbind ( ) is available at 
the client interface for processes that explicitly manage their socket 
descriptors while accessing multiple domains. The call to yp_unbind ( ) 
make the domain unbound, and free all per-process and per-node resources 
used to bind it. 
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If an RPC failure results upon use of a binding, that domain will be 
unbound automatically. At that point, the ypclnt ( ) layer will retry for- 
ever or until the operation succeeds, provided that ypbind is nmning, and 
either 

• the client process cannot bind a server for the proper domain, or 

• RPC requests to the server fail. 

If an error is not RPC-related, or if ypbind is not running, or if a bound 
ypserv process returns any answer (success or failure), the ypclnt layer 
will return control to the user code, either with an error code, or a success 
code and any results. 

ypjgetjdefaultjdoinain (outdcxnain) ; 
char **outdomain; 

The YP lookup calls require a map name and a domain name, at 
minimum. It is assumed that the client process knows the name of the 
map of interest. Client processes should fetch the node's default domain 
by calling ypjgetjdef aultjdoinain ( ) , and use the returned outdomain as 
the indomain parameter to successive YP name service calls. 

yp_inatch(indonvain, inmap, inkey, inkeylen, outval, outvallen) 

char * indomain; 

char *inmap; 

char *inkey; 

int inkeylen; 

char **outval; 

int *outvallen; 

yp__inatch ( ) returns the value associated with a passed key. This key 
must be exact; no pattern matching is available. 

yp_first (indomain, inmap, outkey, outkeylen, outvalr outvallen) 

char *indomain; 

char *inmap; 

char **outkey; 

int *outkeylen; 

char **outval; 

int *outvallen/ 

yp_f irst ( ) returns the first key-value pair from the named map in the 
named domain. 

ypjiext (indomain, inmap, inkey, inkeylen, outkey, outkeylen, outval^ outval 

char * indomain; 

char *inmap; 

char *inkey; 

int inkeylen; 

char **outkey; 

int *outkeylen; 

char **outval; 

int *outvallen; 
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yp^next ( ) returns the next key-value pair in a named map. The inkey 
parameter should be the outkeif returned from an initial call to 
yp_f irst ( ) (to get the second key-value pair) or the one returned from 
the nth call to yp_next ( ) (to get the nth + second key-value pair). 

The concept of first (and, for that matter, of next) is particular to the struc- 
ture of the YP map being processing; there is no relation in retrieval order 
to either the lexical order within any original (non-YP name service) data 
base, or to any obvious numerical sorting order on the keys, values, or 
key-value pairs. The only ordering guarantee made is that if the 
yp_f irst ( ) function is called on a particular map, and then the 
yp_next ( ) function is repeatedly called on the same map at the same 
server imtil the call fails with a reason of yperr_nomore, every entry in the 
data base will be seen exactly once. Further, if the same sequence of 
operations is performed on the same map at the same server, the entries 
will be seen in the same order. 

Under conditions of heavy server load or server failure, it is possible for 
the domain to become unbound, then boimd once again (perhaps to a dif- 
ferent server) while a client is running. This can cause a break in one of 
the enumeration rules; specific entries may be seen twice by the client, or 
not at all. This approach protects the client from error messages that 
would otherwise be returned in the midst of the enumeration. Tlie next 
paragraph describes a better solution to enumerating all entries in a map. 

yp_all(indc3inain, inmap, incallback); 
char *indoinain; 
char *ininap; 

struct ypalljcallback *incallback/ 

yp__all ( ) provides a way to transfer an entire map from server to client 
in a single request using TCP (rather than UDP as with other functions in 
this package). The entire transaction take place as a single RPC request 
and response. yp_jall ( ) can be used just like any other YP name service 
procedure, identify the map in the normal manner, and supply the name 
of a fimction which will he called to process each key-value pair within 
the map. The call to yp_all ( ) returns only when the transaction is com- 
pleted (successfully or imsuccessfuUy), or the foreach function decides 
that it does not want to see any more key-value pairs. 

The third pareimeter to yp_jall ( ) is 

struct ypalljcallback *incallback { 
int (*£oreach) ( ) ; 
char *data; 
1; 

The function foreach is called 

foreach (instatus, inkey, inkeylen, inval, invallen, indata) ; 

int instatus; 

char *inkey; 

int inkeylen; 

char *inval; 

int invallen; 
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char *indata; 

The instaius parameter will hold one of the return status values defined in 
<rpcsvc/yp_prot.h — either YP_TRUE or an error code. (See 
ypprot_err( ), below, for a function which converts a YP name service 
protocol error code to a ypclnt layer error code.) 

The key and value parameters are somewhat different than defined in the 
synopsis section above. First, the memory pointed to by the inkey and 
inval parameters is private to the yp_all( ) fimction, and is overwritten 
with the arrival of each new key-value pair. It is the responsibility of the 
foreach function to do something useful with the contents of that 
memory, but it does not own the memory itself. Key and value objects 
presented to the foreach fimction look exactly as they do in the server's 
map — if they were not NEWLINE-terminated or NULL-terminated in the 
map, they will not be here either. 

The indata parameter is the contents of the incallback->data element 
passed to yp_all ( ) . The data element of the callback structure may be 
used to share state information between the fpreach fimction and the 
mainline code. Its use is optional, and no part of the YP client package 
inspects its contents — cast it to something useful, or ignore it. 

The foreach function is a Boolean. It should return zero to indicate that 
it wants to be called again for further received key-value pairs, or non- 
zero to stop the flow of key-value pairs. If foreach returns a non-zero 
value, it is not called again; the fimctional value of ypjall ( ) is then 0. 

yp_order (indomain, innapr outorder) ; 
char *indomain; 
char *ininap; 
int *outorder; 

yp_prder ( ) returns the order number for a map. 

yp^master (indomin, inmap, outname) ; 
char *indoinain; 
char *inroap; 
char **outnaine; 

yp_inaster ( ) returns the machine name of the master YP server for a 
map. 

char *yperr_string(incode) 
int incode; 

yperr_string ( ) returns a pointer to an error message string that is 
NULL-terminated but contains no period or NEWLINE. 

ypprotjerr (incode) 
unsigned int incode; 

ypprot jerr ( ) takes a YP name service protocol error code as input, and 
returns a ypclnt layer error code, which may be used in turn as an input 
to 3^rr_string( ) . 
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FILES 

/usr/lib/lUbyp.a 
SEE ALSO 

ypservClM), xnallocO), ypupdate(3N), ypf ile8(4) 
DIAGNOSTICS 

All integer functions rettirn 0 if the requested operation is successful, or one of 
the following errors if the operation fails. 

fdefine YPERRBADARSS 

"1 /* args to fvmction are bad */" 

#de£ine YPERR_RPC 

"2 /* RPC failure - domain has been unbound */" 

fdefine YPERRJXMUM 

"3 7* can't bind to server on this domain */" 

fdefine YPERRJOP 

"4 /* no such map in server's domain */" 

fdefine YPERRJCEY 

"5 /* no such key in map */" 

fdefine yperr_yperr 

"6 /* internal yp server or client error */" 

fdefine YPERRRESRC 

"7 /* resource allocation failure */" 

fdefine yperrnomore 

"8 /* no more records in map database */" 

fdefine YPERRPMftP 

"9 /* can't communicate with rpcbinder */" 

fdefine YPERRjCPBBiD 

"10 /* can't communicate with ypbind */" 

fdefine yperr_ypserv 

"11 /* can't communicate with ypserv */" 

fdefine yperrnodom 

"12 /* local domain name not set */" 

fdefine YPERRBADDBfR 

"13 /* yp database is bad */" 

fdefine YPERRVERSfR 

"14 /* yp version mismatch */" 

fdefine YBEBRNXESS 

"15 /* "access violation */" 

fdefine YPERRBUSY 

"16 /* database busy */" 
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NAME 

ypjupdate - changes yp infbnnation 

SYNOPSIS 

♦include <rpcsvc/ypclnt.h> 

ypji:qpdate (domain, map, yppp, key, keylen, data, datalen) 

char *domain; 

char *map; 

unsigned ypqp 

char *key; 

int keylen; 

char *data; 

int datalen; 

DESCRIPTION 

ypjupdate ( ) is used to make changes to the YP database. The syntax is the 
same as that of yp_match ( ) except for the extra parameter ypop which may take 
on one of four values. If it is yp(»jCHANGE then the data associated with the key 
will be changed to the new value. If the key is not found in the database, then 
ypjupdate ( ) will return ypERRjCEY. If ypop has the value yp<»_insert then the 
key-value pair will be inserted into the database. The error YPEE«JCEY is returned 
if the key already exists in the database. To store an item into the database 
without concern for whether it exists already or not, pass ypop as yp0PJ5TC»e and 
no error will be returned if the key already or does not exist. To delete an entry, 
the value of ypop should be ypop_deiete. 

This routine depends upon secure RPC, and will not work unless the network is 
running secure RFC. 

SEE ALSO 

securejtpcON) 
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NAME 

hosts - host name data base 

SYNOPSIS 

/etc/hosts 

DESCRIPTION 

The hosts file contains information regarding the known hosts on the DARPA 
Internet. For each host a single line should be present with the following infor- 
mation: 

Internet-address official-host-name aliases 

Items are separated by any number of SPACE and /or TAB characters. A indi- 
cates the beginning of a comment; characters up to the end of the line are not 
interpreted by routines which search the file. This file is normally created from 
the official host data base maintained at the Network Information Control Center 
(NIO, though local changes may be required to bring it up to date regarding 
unofficial aliases and/or unknown hosts. 

Network addresses are specified in the conventional '/ notation using the 
inetjaddr routine from the Internet address manipulation library, inet(3N). 
Host names may contain any printable character other than a field delimiter, 
NEWLINE, or comment character. 



EXAMPLE 



Here is a typical line from the /etc/hosts file: 
192.9.1.20 gaia 



# John Smith 



FILES 



/etc/hosts 



SEE ALSO 



gethostentON), inetON). 
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NAME 

netconf ig - network configuration database 

SYNOPSIS 

tinclude <netconfig.h> 

DESCRIPTION 

The network configuration database, /etc/netconfig, is a system file used to 
store information about networks connected to the system and available for use. 
The netconfig database and the routines that access it [see getmetoon£ig(3N)] 
are part of the UNIX System V Network Selection component. The Network 
Selection component also includes the environment variable NETPATH and a group 
of routines that access the netconfig database using NETPATH components as 
links to the netconfig entries. NETPATH is described in sh(l); the NETPATH access 
routines are discussed in getnetpathON). 

netconfig contains an entry for each network available on the S3^tem. Entries 
are separated by newlines. Relds are separated by whitespace and occur in the 
order in which they are described below. Whitespace can be embedded as 
'ybhmlf' or '\ta>'\ Backslashes may be embedded as "\\". Each field 
corresponds to an element in the struct netconfig structure, struct netcon- 
fig and the identifiers described on this manual page are defined in 
/usr/include/netconf ig . h. 

nettvork ID 

A string used to uniquely identify a network, network ID consists of non- 
null characters, and has a length of at least 1. No maximum length is 
specified. This namespace is locally significant and the local system 
administrator is the naming authority. All network IDs on a system must 
be unique. 

semantics 

The semantics field is a string identifing the "semantics" of the network, 
i.e., the set of services it supports, by identifying the service interface it 
provides. The semantics field is mandatory. The following semantics are 
recognized. 

tpijclts Transport Provider Interface, connectionless 

tpijcots Transport Provider Interface, connection oriented 

tpijcots_prd 

Transport Provider Interface, connection oriented, sup- 
ports orderly release. 

flag The flag field records certain two-valued ("true" and "false") attributes of 
networks, flag is a string composed of a combination of characters, each of 
which indicates the value of the corresponding attribute. If the character is 
present, the attribute is "true." If the character is absent, the attribute is 
"false." "-" indicates that none of the attributes is present. Only one 
character is currently recognized: 
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V Visible ("default") network. Used when the environment 

variable NETPATH is unset. 

protoa>l family 

The protocol family and protocol name fields are provided for protocol- 
specific applications. 

The protocol family field contains a string that identifies a protocol family. 
The protocol family identifier follows the same rules as those for network 
IDs, that is, the string consists of non-null characters; it has a length of at 
least 1; and there is no maximum length specified. A in the protocol 
family field indicates that no protocol family identifier applies, that is, the 
network is experimental. The following are examples: 



loc^>back Loopback (local to host), 

inet Internetwork: UDP, TCP, etc. 

ixnplink ARPANET imp addresses 

pup PUP protocols: e.g. BSP 

chaos MIT CHAOS protocols 

ns XEROX NS protocols 

nbs NBS protocols 

ecroa European Computer Manufacturers Association 

datakit DATAKIT protocols 

ocitt CCnr protocols, X.25, etc. 

sna IBM SNA 

decnet DECNET 

dli Direct data link interface 

lat LAT 

hylink NSC Hyperchannel 

aqppletalk Apple Talk 

nit Network Interface Tap 

ieee802 IEEE 802.2; also ISO 8802 

osi Umbrella for all families used by OSI (e.g., protosw 
lookup) 

x25 CCITT X.25 in particular 

osinet AFl = 47, IDI = 4 

gosip U.S. Government OSI 



protocol name 

The protocol name field contains a string that identifies a protocol. The pro- 
tocol name identifier follows the same rules as those for network IDs, that Js, 
the string consists of non-NULL characters; it has a length of at least 1; and 
there is no maximum length specified. The following protocol names are 
recognized. A indicates that none of the names listed applies. 

tcp Transmission Control Protocol 

u<^p User Datagram Protocol 

ionp Internet Control Message Protocol 
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FILES 



network device 

The network device is the full pathname of the device used to connect to the 
transport provider. Typically, this device will be in the /dev directory. 
The network device must be specified. 

directory lookup libraries 

The directory lookup libraries support a "directory service'' (a name-to- 
address mapping service) for the network. This service is implemented by 
the UNIX System V Name-to- Address Mapping feature. If a network is not 
provided with such a library, the netdir feature will not work. A ' in 
this field indicates the absence of any lookup libraries, in which case 
name-to-address mapping for the network is non-ftmctional. The directory 
lookup library field consists of a comma-separated list of full pathnames to 
d5mamically linked libraries. Commas may be embedded as "\/'; 
backslashs as '^\". 

Lines in /etc/netconf ig that begin with a sharp sign (#) in colimm 1 are treated 
as comments. 

The struct netconfig structure includes the following members corresponding 
to the fields in in the netconfig database entries: 

char * ncjtietid Network ID, including NULL terminator 

unsigned long ncjsemantics Semantics 

vmsigned long nc_f lag Flags 

char * nc_protof mly Protocol family 

char * nc_proto Protocol name 

char * nc_device Full pathname of the network device 

unsigned long nc^nlookvqps Number of directory lookup libraries 

char ** nc^lookiips Full pathnames of the directory lookup 

libraries themselves 

unsigned long ncjLinused[9] Reserved for future expansion (not advertised 

to user level) 

The ncjBeinantics field takes the following values, corresponding to the seman- 
tics identified above: 

NCJTPIjCLTS 
NC_TPI_COTS 
NCTPI_CX)TSJDRD 

The nc_f lag field is a bitfield. The following bit, corresponding to the attribute 
identified above, is currently recognized. NCJJOFLAG indicates the absence of any 
attributes. 

NCJVISIBLE 

/etc/netconf ig 
/usr/include/netconf ig . h 
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SEE ALSO 

netdir_jgetbynaine(3N), getnetcx)nf ig(3N), getnetpath(3N), netoon£i9(4) 
Network Programmer's Guide 
System Administrator's Guide 
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NAME 

publickey - public key database 

SYNOPSIS 

/etc/publickey 

DESCRIPTION 

/etc/publickey is the public key database used for secure RPC. Each entry in 
the database consists of a network user name (which may either refer to a user or 
a hostname), followed by the user's public key (in hex notation), a colon, and 
then the user's secret key encrypted with a password (also in hex notation). 

This file is altered either by the user through the chkey(l) command or by the 
system administrator through the newkeyd) command. 

SEE ALSO 

chkeyd), newkeyd), publickey(3ND. 
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NAME 

rpc - rpc program number data base 

SYNOPSIS 

rpc 

DESCRIPTION 

The rpc program number database contains user readable names that can be used 
in place of E^^C program numbers. Each line has the following information: 

name of server for the RPC program 

RPC program number 

aliases 

Items are separated by any number of blanks and /or tab characters. A # indi- 
cates the beginning of a comment; characters up to the end of the line are not 
interpreted by routines which search the file. 

Below is an example of an RPC database: 



« 
# 
* 


rpc 




rpcbind 


100000 


portmap sunrpc port:xnapper 


rusersd 


100002 


rusers 


nfs 


100003 


nfsprog 


nountd 


100005 


mount showmount 


walld 


100008 


rwall shutdown 


sprayd 


100012 


spray 


llcx^kmgr 


100020 




nlockmgr 


100021 




status 


100024 




bootparam 


100026 




keyserv 


100029 


keyserver 
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NAME 

ttydefs - file contains terminal line settings information for ttymon 
DESCRIPTION 

/etc/ttydefs is an administrative file that contains information used by ttymon 
to set up the speed and terminal settings for a TTY port. 

The ttydefs file contains the following fields: 

ttylabel The string ttynon tries to match against the TTY port's ttyldbel 

field in the port monitor administrative file. It often describes 
the speed at which the terminal is supposed to run, for example, 
1200. 

initial-flags Contains the initial tennio(7) settings to which the terminal is to 
be set. For example, the system administrator will be able to 
specify what the default erase and kill characters will be. initial- 
flags must be specified in the sjmtax recognized by the stty com- 
mand. 

final-flags final-flags must be specified in the same format as initial-flags. 

ttymon sets these final settings after a connection request has 
been made and immediately prior to invoking a port's service. 

autobaud If the autobaud field contains the character 'A', autobaud will be 

enabled. Otherwise, autobaud will be disabled, ttymon deter- 
mines what line speed to set the TTY port to by anal)rzing the 
carriage returns entered. If autobaud has been disabled, the hunt 
sequence is used for baud rate determination. 

nextlabel If the user indicates that the current terminal setting is not 

appropriate by sending a BREAK, ttymon searchs for a ttydefs 
entry whose ttylahel field niatches the nextlabel field. If a match is 
found, ttymon uses that field as its ttylabel field. A series of 
speeds is often linked together in this way into a closed set called 
a himt sequence. For example, 4800 may be linked to 1200, 
which in turn is linked to 2400, which is finally linked to 4800. 

SEE ALSO 

ttymon(lM), sttydef s(lM) 

System Administrator's Guide, "Service Access" 
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NAME 

updaters - configuration file for YP updating 

SYNOPSIS 

/var/yp/updaters 

DESCRIPTION 

The file /var/yp/updaters is a makefile (see maked)) which is used for updating 
YP databases. Databases can only be updated in a secure network, that is, one 
that has a publickey(4) database. Each entry in the file is a make target for a 
particular YP database. For example, if there is a YP database named 
piiblickey. byname that can be updated, there should be a make target named 
publickey. byname in the updaters file with the command to update the file. 

The information necessary to make the update is passed to the update command 
through standard input. The information passed is described below (all items are 
followed by a NEWLINE, except for the actual bytes of key and actual bytes of 
date). 

• Network name of client wishing to make the update (a string) 

• Kind of update (an integer) 

• Nimiber of bytes in key (an integer) 

• Actual bytes of key 

• Nimiber of bytes in data (an integer) 

• Actual bytes of data 

After getting this information through standard input, the command to update 
the particular database should decide whether the user is allowed to make the 
change. If not, it should exit with the status YPERRjyXESS. If the user is allowed 
to make the change, the command should make the change and exit with a status 
of zero. If there are any errors that may prevent the updater from making the 
change, it should exit with the status that matches a valid YP error code described 
in <rpcsvc/ypclnt . h>. 

FILES 

/var/yp/updaters 
SEE ALSO 

make(l), ypupdated(lM), ypupdateO), publickey(4) 
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NAME 

ypf iles - the YP database and directory structure 
DESCRIPTION 

The YP network lookup service uses a distributed, replicated database of dbm files 
contained in the /var/yp directory hierarchy on each YP server. A dbm database 
consists of two files, one has the filename extension .pag and the other has the 
filename extension .dir. For instance, the database named publickey, is imple- 
mented by the pair of files publickey. pag and publickey. dir. 

A dbm database served by the YP is called a YP map. A YP ypdomain is a subdirec- 
tory of /var/yp containing a set of YP maps. Any number of YP domains can 
exist. Each may contain any number of maps. 

No maps are required by the YP lookup service itself, although they may be 
required for the normal operation of other parts of the system. There is no list of 
maps which YP serves — if the map exists in a given domain, and a client asks 
about it, the YP will serve it. For a map to be accessible consistently, it must exist 
on all YP servers that serve the domain. To provide data consistency between the 
replicated maps, an entry to run ypxfr periodically should be made in the 
privileged user's crontab file on each server. More information on this topic is 
in ypxfr(lM). 

YP maps should contain two distinguished key-value pairs. The first is the key 
YP_IAST_MDDIFIED, having as a value a ten-character ASCII order number. The 
order number should be the system time in seconds when the map was built. 
The second key is YP_MASTER_HAME, with the name of the YP master server as a 
value. makedbm(lM) generates both key-value pairs automatically. A map that 
does not contain both key-value pairs can be served by the YP, but the ypserv 
process will not be able to return values for "Get order number" or "Get master 
name" requests. See ypserv(lM). In addition, values of these two keys are used 
by ypxfr when it transfers a map from a master YP server to a slave. If ypxfr 
cannot figure out where to get the map, or if it is imable to determine whether 
the local copy is more recent than the copy at the master, extra command line 
switches must be set when it is run. 

YP maps must be generated and modified only at the master server. They are 
copied to the slaves using ypxfr(lM) to avoid potential byte-ordering problems 
among YP servers running on machines with different architectures, and to 
minimize the amount of disk space required for the dbm files. The YP database 
can be initially set up for both masters and slaves by using ypinit(lM). 

After the server databases are set up, it is probable that the contents of some 
maps will change. In general, some ASCII source version of the database exists on 
the master, and it is changed with a standard text editor. The update is incor- 
porated into the YP map and is propagated from the master to the slaves by run- 
ning /var/yp/Makef ile, see ypmake(lM). All Sun-supplied maps have entries in 
/var/yp/Makef ile; if a YP map is added, edit this file to support the new map. 
The makefile uses makedbmdM) to generate the YP map on the master, and 
yppush(lM) to propagate the changed map to the slaves, yppush is a client of 
the map ypservers, which lists all the YP servers. For more information on this 
topic, see yppushdM). 
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FILES 

/var/yp 

/var/yp/aliases 
/var/yp/Makefile 

SEE ALSO 

roakedbmdM), ypinit(lM), ypnake(lM), yppoll(lM), yppushdM), ypserv(lM), 
ypxfr(lM), dbn<3), publickey(4) 



Page 2 



10/89 



environ (5) 



environ (5) 



NAME 

enviixjn - user environment 
DESCRIPTION 

When a process begins execution, exec routines make available an array of strings 
called the environment [see exec(2)]. By convention, these strings have the form 
variable==mlue, for example, PATH»/8bin:/usr/sbin. These environmental vari- 
ables provide a way to make information about a program's environment avail- 
able to programs. The following environmental variables can be used by applica- 
tions and are expected to be set in the target run-time environment. 

HOME The name of the user's login directory, set by login(l) from the 

password fUe (see passwd(4)). 

LANG The string used to specify localization information that allows users 

to work with different national conventions. The setlocale(3C) 
function looks for the LANG environment variable when it is cdled 
with as the locale argument. LANG is used as the default locale if 
the corresponding environment variable for a particular category is 
unset. 

For example, when setlocaleO is invoked as 

set locale (LCJCTYPE, ""), 
setlocaleO will query the LC_CTYPE environment variable first to 
see if it is set and non-null. If LCjCTYPE is not set or null, then set- 
localeO will check the LANG environment variable to see if it is set 
and non-null. If both LANG and LCJCTYPE are unset or null, the 
default c locale will be used to set the LCjCTYPE category. 

Most commands will invoke 

setlocale(LC_ALL, "") 
prior to any other processing. This allows the command to be used 
with different national conventions by setting the appropriate 
environment variables. 

The following environment variables are supported to correspond 
with each category of setlocaleOC): 

LCjCOLLATE This category specifies the collation sequence being 
used. The information corresponding to this 
category is stored in a database created by the 
colltbl(lM) command. This environment variable 
affects strcollOC) and strxfnn(3C). 

LCjCTYPE This category specifies character classification, char- 
acter conversion, and widths of multibyte charac- 
ters. The information corresponding to this 
category is stored in a database created by the 
chrtJDl(lM) command. The default C locale 
corresponds to the 7-bit ASCII character set. This 
environment variable is used by ctype(3C), 
iitx2har(3C), and many commands; for example: 
cat(l), ed(l), ls(l), and vi(l). 
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This category specifies the language of the message 
database being used. For example, an application 
may have one message database with French mes- 
sages, and another database with German messages. 
Message databases are created by the mkmsgsdM) 
command. This environment variable is used by 
exstr(l), gettxt(l), gettxt(3C), and srchtxt(l). 

This category specifies the monetary symbols and 
delimiters used for a particular locale. The informa- 
tion corresponding to this category is stored in a 
database created by the inontbl(lM) command. 
This environment variable is used by 
localeconv(3C) . 

LC_NUMERIC This category specifies the decimal and thousands 
delimiters. The information corresponding to this 
category is stored in a database created by the 
chrtbl(lM) command. The default C locale 
corresponds to " . " as the decimal delimiter and no 
thousands delimiter. This environment variable is 
used by localeconv(3C), printf(3C), and 
strtod(3C). 

LCjriME This category specifies date and time formats. The 

information corresponding to this category is stored 
in a database specified in str£tixne(4). The default 
C locale corresponds to U.S. date and time formats. 
This environment variable is used by many com- 
mands and functions; for example: at(l), calen- 
dar(l), dated), strftimeOC), and getdateOC). 

MSGVERB Controls which standard format message components fmtmsg selects 
when messages are displayed to stderr [see fmtmsgd) and 
fmtrosgOC)]. 

SEVJiEVEL Define severity levels and associate and print strings with them in 
standard format error messages [see addseverity(3C), iSmtmsgd), 
and fmtinsg(3C)]. 

NETPATH A colon-separated list of network identifiers. A network identifier is 
a character string used by the Network Selection component of the 
system to provide application-specific default network search paths. 
A network identifier must consist of non-NULL characters and must 
have a length of at least 1. No maximtim length is specified. Net- 
work identifiers are normally chosen by the system administrator. 
A network identifier is also the first field in any /etc/netconf ig 
file entry. NETPATH thus provides a link into the /etc/netconf ig 
file and the information about a network contained in that network's 
entry, /etc/netconf ig is maintained by the system administrator. 
The library routines described in getnetpath(3N) access the NET- 
PATH environment variable. 



LC MESSAGES 



LC MONETARY 
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NLSPATH Contains a sequence of templates which catopen(3C) uses when 
attempting to locate message catalogs. Each template consists of an 
optional prefix, one or more substitution fields, a fQename and an 
optional suffix. 

For example: 

NLSPATH«"/sy8tein/nl8lib/%N . cat" 

defines that catopenO should look for all message catalogs in the 
directory /systexn/nlslUb, where the catalog name should be con- 
structed from the name parameter passed to catc^enO, %N, with 
the suffix .cat. 

Substitution fields consist of a % symbol, followed by a single-letter 
keyword. The following keywords are currently defined: 



%N The value of the name parameter 

passed to catopenO. 

%L The value of LANG. 

%1 The language element from LANG. 

%t The territory element from LANG. 

%c The codeset element from LANG. 

%% A single % character. 

An empty string is substituted if the specified value is not currently 
defined. The separators and "."are not included in %t and %c 
substitutions. 

Templates defijied in NLSPATH are separated by colons (:). A lead- 
ing colon or two adjacent colons (: :) is equivalent to specifying %N. 

For example: 

NLSPATH*" : %N . cat : /nlslib/%L/%N . cat" 

indicates to catopenO that it should look for the requested message 
catalog in name, name. cat and /nlslib/$LANG/niZw^.cat. 

PATH The sequence of directory prefixes that sh(l), timed), nice(l), 

nohupd), etc., apply in searching for a file known by an incomplete 
path name. The prefixes are separated by colons ( : ). logind) sets 
PATH=/usr/bin. (For more detail, see shd).) 

TERM The kind of terminal for which output is to be prepared. This infor- 

mation is used by commands, such as itirtd) or vid), which may 
exploit special capabilities of that terminal. 

TZ Time zone information. The contents of the environment variable 

named TZ are used by the functions ctime(3C), localtimeO (see 
ctimeOO), strftimeOO and inktime(3C) to override the default 
timezone. If the first character of TZ is a colon (:), the behavior is 
implementation defined, otherwise TZ has the form: 

stdoffset [ dst [ offset ] , [ start [ /time ],end[ /time ] ] ] 
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std and dst 

Three or more bytes that are the designation for the standard 
(std) and daylight savings time (dst) timezones. Only std is 
required, if dst is missing, then daylight savings time does 
not apply in this locale. Upper- and lower-case letters are 
allowed. Any characters except a leading colon (:), digits, a 
comma (, ), a minus (-) or a plus M are allowed. 

offset Indicates the value one must add to the local time to arrive 
at Coordinated Universal Time. The offset has the form: 

hh [ : mm I : ss ] ] 

The minutes (mm) and seconds (ss) are optional. The hour 
(hh) is required and may be a single digit. The offset follow- 
ing std is required. If no offset follows dst , daylight savings 
time is assumed to be one hour ahead of standard time. One 
or more digits may be used; the value is always interpreted 
as a decimal number. The hour must be between 0 and 24, 
and the minutes (and seconds) if present between 0 and 59. 
Out of range values may cause impredictable behavior. If 
preceded by a the timezone is east of the Prime Meri- 
dian; otherwise it is west (which may be indicated by an 
optional preceding sign). 

start /time, end/ time 

Indicates when to change to and back from daylight savings 
time, where start/time describes when the change from stan- 
dard time to daylight savings time occurs, and end/time 
describes when the change back happens. Each time field 
describes when, in current local time, the change is made. 

The formats of start and end are one of the following: 

Jn The Julian day n (1 < « < 365). Leap days are 
not counted. That is, in all years, February 28 is 
day 59 and March 1 is day 60. It is impossible 
to refer to the occasional February 29. 

n The zero-based Julian day (0 ^ n < 365). Leap 
days are counted, and it is possible to refer to 
February 29. 

Mm.n.d , 

The d^"^ day, (0 < i < 6) of week n of month m 
of the year (1 < n < 5, 1 < m < 12), where week 
5 means "the last d-day in month m" which 
may occur in either the fourth or the fifth 
week). Week 1 is the first week in which the 
d day occurs. Day zero is Sunday. 
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Implementation specific defaults are used for start and end if 
these optional fields are not given. 

The time has the same format as offset except that no leading 
sign (' ~" or "+'0 is allowed. The default, if time is not given 
is 02:00:00. 

Further names may be placed in the environment by the export command and 
name=value arguments in sh(l), or by exec(2). It is unwise to conflict with cer- 
tain shell variables that are frequently exported by .profile files: MAIL, PSl, 
PS2, IFS (see prof ile(4)). 

SEE ALSO 

chrtJDl(lM), colltbl(lM), inkmsgs(lM), montbl(lM), netconf ig(4), 
strf tiine(4), passwd(4), prof ile(4) in the System Administrator's Reference 
Manual, 

exec(2X addseverity(3C), catopenOC), ctimeOQ, ctype(3C), fintinsg(3C), 
getdateOC), gettxt(3C), localeconv(3C), itbchar(3C), inktimB(3C), printf (3C), 
strcoll(3C), strftiine(3C), strtod(3Q, strxfnn(3C), strftiine(4), 
timezone(4). 

cat(l), dated), ed(l), fmtmsgd), ls(l), login(l), nice(l), nohupd), sh(l), 

sort(l), timed), vid) in the User's Reference Manual. 

getnetpath(3N), in the Programmer's Guide: NetzvorJdng Interfaces. 

nmd) in the DOCUMENTER'S WORKBENCH Software Technical Discussion and 

Reference Manual. 
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NAME 

ICMP - Internet Control Message Protocol 

SYNOPSIS 

♦include <sys/socket .h> 
♦include <netinet/in.h> 
♦include <netinet/ip_icnp . h> 

s = socket (AF_INET^ SOCK_RAW, proto) ; 

t « t_open{"/dev/icinp", OJEa)WR); 

DESCRIPTION 

ICMP is the error and control message protocol used by the Internet protocol fam- 
ily. It is used by the kernel to handle and report errors in protocol processing. It 
may also be accessed by programs using the socket interface or the Transport 
Level Interface (TLI) for network monitoring and diagnostic functions. When 
used with the socket interface, a raw socket type is used. The protocol number 
for ICMP, used in the proto parameter to the socket call, can be obtained from 
getprotdbyname ( ) [see getprotoent(3N)l. ICMP file descriptors and sockets are 
connectionless, and are normally used with the tjsndudata / t_j:cvudata and 
the sendto( ) / recvfromC ) calls. 

Outgoing packets automatically have an Internet Protocol (IP) header prepended 
to them. Incoming packets are provided to the user with the IP header and 
options intact. 

ICMP is an datagram protocol layered above IP. It is used internally by the protcol 
code for various purposes including routing, fault isolation, and congestion con- 
trol. Receipt of an ICMP redirect message will add a new entry in the routing 
table, or modify an existing one. ICMP messages are routinely sent by the proto- 
col code. Received ICMP messages may be reflected back to users of higher-level 
protocols such as TCP or UDP as error returns from system calls. A copy of all 
ICMP message received by the system is provided to every holder of an open 
ICMP socket or TLI descriptor. 

SEE ALSO 

send(2), getprotoentON)/ recvfrQm(3N)/ tjccvudataON), t_sndudata(3N)/ 
routing(4), inet(7), ip(7). 

Postel, Jon, Internet Control Message Protocol — DARPA Internet Program Protocol 
Specification, RFC 792, Network Information Center, SRI International, Menlo Park, 
Calif., September 1981. 

DIAGNOSTICS 

A socket operation may fail with one of the following errors returned: 

EISCX)NN An attempt was made to establish a connection on a socket 

which already has one, or when trying to send a datagram 
with the destination address specified and the socket is 
already connected. 

ENOTOONN An attempt was made to send a datagram, but no destina- 

tion address is specified, and the socket has not been con- 
nected. 
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ENOBUFS The system ran out of memory for an internal data struc- 

ture. 

EADDBNOTAVAIL An attempt was made to create a socket with a network 
address for which no network interface exists. 

NOTES 

Replies to ICMP echo messages which are source routed are not sent back using 
inverted source routes, but rather go back through the normal routing mechan- 
isms. 
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NAME 

IP - Internet Protocol 

SYNOPSIS 

♦include <sys/socket .h> 
♦include <netinet/in.h> 

s « socket (AP_IKET, SOCKJUW, proto) ; 

t « t_ppen ("/dev/rawip", ojam); 

d = open ("/dev/ip"r 0_RDWR); 

DESCRIPTION 

IP is the internetwork datagram delivery protocol that is central to the Internet 
protocol family. Programs may use IP through higher-level protocols such as the 
Transmission Control Protocol (TCP) or the User Datagram Protocol (UDP), or 
may interface directly to IP. See tcp(7) and udp(7). Direct access may be via the 
socket interface (using a raw socket) or the Transport Level Interface (TLI). The 
protocol options defined in the IP specification may be set in outgoing datagrams. 

The STREAMS driver /dev/rawip is the TU transport provider that provides raw 
access to IP. The device /dev/ip is the multiplexing STREAMS driver that imple- 
ments the protocol processing of IP. The latter connects below to datalink provid- 
ers [interface drivers, see if(3N)], and above to tranport providers such as TCP 
and UDP. 

Raw IP sockets are connectionless and are normally used with the sendto ( ) and 
recvfrom( ) calls, [(see send(2) and recv(2)] although the connect(2) call may 
also be used to fix the destination for future datagrams [in which case the read(2) 
or recv(2) and write(2) or send(2) calls may be used]. If proto is zero, the 
default protocol, IPPRDTOJRAW, is used. If proto is non-zero, that protocol 
number will be set in outgoing datagrams and will be used to filter incoming 
datagrams. An IP header will be generated and prepended to each outgoing 
datagram; received datagrams are returned with the IP header and options intact. 

A single socket option, IPjOPTIONS, is supported at the IP level. This socket 
option may be used to set IP options to be included in each outgoing datagram. 
IP options to be sent are set with setsockopt ( ) [see getsockopt(2)]. The get- 
sockopt(2) call returns the IP options set in the last setsockopt ( ) call. IP 
options on received datagrams are visible to user programs only using raw IP 
sockets. The format of IP options given in setsockopt ( ) matches those defined 
in the IP specification with one exception: the list of addresses for the source rout- 
ing options must include the first-hop gateway at the beginning of the list of gate- 
ways. The first-hop gateway address will be extracted from the option list and 
the size adjusted accordingly before use. IP options may be used with any socket 
type in the Internet family. 

At the socket level, the socket option SOJX)NTRDaTE may be applied. This option 
forces datagrams being sent to bypass the routing step in output. Normally, IP 
selects a network interface to send the datagram, and possibly an intermediate 
gateway, based on an entry in the routing table. See routing(4). When 
spjXJNTRCXJTE is set, the datagram will be sent using the interface whose network 
number or full IP address matches the destination address. If no interface 
matches, the error ENETONRCH will be returned. 
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Raw IP datagrams can also be sent and received using the TLI connectionless 
primitives. 

Datagrams flow through the IP layer in two directions: from the network up to 
user processes and from user processes dozvn to the network. Using this orienta- 
tion, IP is layered above the network interface drivers and below the transport pro- 
tocols such as UDP and TCP. The Internet Control Message Protocol (ICMP) is logi- 
cally a part of IP. See icnp(7). 

IP provides for a checksum of the header part, but not the data part of the 
datagram. The checksimi value is computed and set in the process of sending 
datagrams and checked when receiving datagrams. IP header checksumming may 
be disabled for debugging purposes by patching the kernel variable ipcksum to 
have the value zero. 

IP options in received datagrams are processed in the IP layer according to the 
protocol specification. Currently recognized IP options include: security, loose 
source and record route (LSRR), strict source and record route (SSRR), record 
route, stream identifier, and internet timestamp. 

The IP layer will normally forward received datagrams that are not addressed to 
it. Forwarding is under the control of the kernel variable ivfonvarding: if ipfor- 
warding is zero, IP datagrams will not be forwarded; if ipforwarding is one, IP 
datagrams will be forwarded, ipforwarding is usually set to one only in machines 
with more than one network interface (internetwork routers). This kernel vari- 
able can be patched to enable or disable forwarding. 

The IP layer will send an ICMP message back to the source host in many cases 
when it receives a datagram that can not be handled. A time exceeded ICMP 
message will be sent if the time to live field in the IP header drops to zero in the 
process of forwarding a datagram. A destination unreachable message will be 
sent if a datagram can not be forwarded because there is no route to the final 
destination, or if it can not be fragmented. If the datagram is addressed to the 
local host but is destined for a protocol that is not supported or a port that is not 
in use, a destination unreachable message will also be sent. The IP layer may 
send an ICMP source quench message if it is receiving datagrams too quickly. 
ICMP messages are only sent for the first fragment of a fragmented datagram and 
are never returned in response to errors in other ICMP messages. 

The IP layer supports fragmentation and reassembly. Datagrams are fragmented 
on output if the datagram is larger than the maximimt transmission unit (MTU) of 
the network interface. Fragments of received datagrams are dropped from the 
reassembly queues if the complete datagram is not reconstructed within a short 
time pericxi. 

Errors in sending discovered at the network interface driver layer are passed by 
IP back up to the user process. 

SEE ALSO 

read(2), write(2), connectOND, getsockopt(3N), recv(3N), send(3N), 
routing(4), icmp(7), inet(7) tcp(7), udp(7). 
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Postel, Jon, Internet Protocol - DARPA Internet Program Protocol Specification, RFC 
791, Network Information Center, SRI International, Menlo Park, Calif., September 
1981. 

DIAGNOSTICS 

A socket operation may fail with one of the following errors returned: 

EACCESS A IP broadcast destination address was specified and the 

caller was not the privileged user. 

EISCONN An attempt was made to establish a connection on a socket 

which already had one, or to send a datagram with the des- 
tination address specified and the socket was already con- 
nected. 

EMSGSIZE An attempt was made to send a datagram that was too 

large for an interface, but was not allowed to be frag- 
mented (such as broadcasts). 

ENETUNREACH An attempt was made to establish a connection or send a 

datagram, where there was no matching entry in the rout- 
ing table, or if an ICMP destination imreachable message 
was received. 

ENOTOONN A datagrem was sent, but no destination address was 

specified, and the socket had not been connected. 

ENOBUFS The system ran out of memory for fragmentation buffers or 

other internal data structure. 

EADDRNOTAVAIL An attempt was made to create a socket with a local 
address that did not match any network interface, or an IP 
broadcast destination address was specified and the net- 
work interface does not support broadcast. 

The following errors may occur when setting or getting IP options: 

EINVAL An unknown socket option name was given. 

EINVAL The IP option field was improperly formed; an option field 

was shorter than the minimtmi value or longer than the 
option buffer provided. 

Raw sockets should receive ICMP error packets relating to the protocol; currently 
such packets are simply discarded. 

Users of higher-level protocols such as TCP and UDP should be able to see 
received IP options. 
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NAME 

sockio - ioctls that operate directly on sockets 

SYNOPSIS 

finclude <sys/sockio.h> 

DESCRIPTION 

The lOCTL's listed in this manual page apply directly to sockets, independent of 
any underl5dng protocol. The setsockppt call (see getsockppt(3N)) is the pri- 
mary method for operating on sockets, rather than on the tmderl5dng protocol or 
network interface, ioctls for a specific network interfoce or protocol are docu- 
mented in the manual page for that interface or protocol. 

SIOCSPGRP The argument is a pointer to an int. Set the process-group 

ID that will subsequently receive SI6I0 or SIGURG signals 
for the socket referred to by the descriptor passed to ioctl 
to the value of that int. 

SICX:gpgrp The argument is a pointer to an int. Set the value of that 

int to the process-group ID that is receiving SIGIO or 
SIGURG signals for the socket referred to by the descriptor 
passed to ioctl. 

SIOCCATMARK The argument is a pointer to an int. Set the value of that 

int to 1 if the read pointer for the socket referred to by the 
descriptor passed to ioctl points to a mark in the data 
stream for an out-of-band message. Set the value of that 
int to 0 if the read pointer for the socket referred to by the 
descriptor passed to ioctl does not point to a mark in the 
data stream for an out-of-band message. 

SEE ALSO 

ioctl(2), getsockopt(2), f ilio(4) 
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NAME 

TCP - Internet Transmission Control Protocol 

SYNOPSIS 

♦include <sys/socket.h> 
♦include <netinet/in.h> 

8 - socket (AF_INET, SCXaC_STREAM, 0); 

t - t_open("/dev/tqp", 0_RDWR); 

DESCRIPTION 

TCP is the virtual circuit protocol of the Internet protocol family. It provides reli- 
able, flow-controlled, in order, two-way transmission of data. It is a byte-stream 
protocol layered above the Internet Protocol (IP), the Internet protocol family's 
internetwork datagram delivery protocol. 

Programs can access TCP using the socket interface as a SOCK_STREAM socket type, 
or using the Transport Level Interface (TLI) where it supports the connection- 
oriented (T_OOTSjORD) service type. 

TCP uses IP's host-level addressing and adds its own per-host collection of port 
addresses. The endpoints of a TCP connection are identified by the combination 
of an IP address and a TCP port number. Although other protocols, such as the 
User Datagram Protocol (UDP), may use the same host and port address format, 
the port space of these protocols is distinct. See inet(7) for details on the com- 
mon aspects of addressing in the Internet protocol family. 

Sockets utilizing TCP are either active or passive. Active sockets initiate connec- 
tions to passive sockets. Both types of sockets must have their local IP address 
and TCP port number bound with the bind(2) system call after the socket is 
created. By default, TCP sockets are active. A passive socket is created by calling 
the listen(2) system call after binding the socket with bind( ) . This establishes 
a queueing parameter for the passive socket. After this, connections to the pas- 
sive socket can be received with the accept(2) system call. Active sockets use the 
connect(2) call after binding to initiate connections. 

By using the special value INADDR_ANY, the local IP address can be left 
unspecified in the bind() call by either active or passive TCP sockets. This 
feature is usually used if the local address is either unknown or irrelevant. If left 
unspecified, the local IP address will be bound at connection time to the address 
of the network interface used to service the connection. 

Once a connection has been established, data can be exchanged using the read(2) 
and write(2) system calls. 

TCP supports one socket option which is set with setsockopt ( > and tested with 
getsockopt(2). Under most circimistances, TCP sends data when it is presented. 
When outstanding data has not yet been acknowledged, it gathers small amounts 
of output to be sent in a single packet once an acknowledgement is received. For 
a small number of clients, such as window systems that send a stream of mouse 
events which receive no replies, this packetization may cause significant delays. 
Therefore, TCP provides a boolean option, TCP_NODELAY (defined in 
/usr/include/netinet/tcp.h), to defeat this algorithm. The option level for 
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the setsockoptO call is the protocol number for TCP, available from 
getprotobynaine ( ) [see getprotoent(3N)]. 

Options at the IP level may be used with TCP; See ip(7). 

TCP provides an urgent data mechanism, which may be invoked using the out- 
of-band provisions of send(2). The caller may mark one byte as urgent with the 
MSGJDOB flag to send(2). This sets an urgent pointer pointing to this byte in the 
TCP stream. The receiver on the other side of the stream is notified of the urgent 
data by a SIGUR6 signal. The SIOCA.TMARK ioctl ( ) request returns a value indi- 
cating whether the stream is at the urgent mark. Because the system never 
returns data across the urgent mark in a single read(2) call, it is possible to 
advance to the urgent data in a simple loop which reads data, testing the socket 
with the SIOCATMARK ioctl ( ) request, until it reaches the mark. 

Incoming connection requests that include an IP source route option are noted, 
and the reverse source route is used in responding. 

A checksum over all data helps TCP implement reliability. Using a window-based 
flow control mechanism that makes use of positive acliiowledgements, sequence 
nimibers, and a retransmission strategy, TCP can usually recover when datagrams 
are damaged, delayed, duplicated or delivered out of order by the imderlying 
communication medium. 

If the local TCP receives no acknowledgements from its peer for a period of time, 
as would be the case if the remote machine crashed, the connection is closed and 
an error is returned to the user. If the remote machine reboots or otherwise loses 
state information about a TCP connection, the connection is aborted and an error 
is returned to the user. 

SEE ALSO 

read(2), write(2), acceptON), bind(3N), connectON), getprotoent(3N), 
getsockoptON), listen(3N), send(31SD, inet(7), ip(7). 

Postel, Joit, Transmission Control Protocol - DARPA Internet Program Protocol 
Specification, RFC 793, Network Information Center, SRI International, Menlo Park, 
Calif., September 1981. 

DIAGNOSTICS 

A socket operation may fail if: 

EISOONN A connect ( ) operation was attempted on a socket on 

which a connect ( ) operation had already been performed. 

ETIMEDOOT A connection was dropped due to excessive retransmis- 

sions. 

ECX)NNBESET The remote peer forced the connection to be closed (usually 

because the remote machine has lost state information 
about the connection due to a crash). 

ECX)NNREFUSED The remote peer actively refused connection establishment 

(usually because no process is listening to the port). 
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EADDRINUSE 

EADDBNOTAVAIL 
EACCES 

ENOBUFS 



A bind ( ) operation was attempted on a socket with a net- 
work address/port pair that has already been bound to 
another socket. 

A bind ( ) operation was attempted on a socket with a net- 
work address for which no network interface exists. 

A bindO operation was attempted with a reserved port 
number and the effective user ID of the process was not the 
privileged user. 

The system ran out of memory for internal data structures. 
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ticlts, ticotSr ticotsord - loopback transport providers 

SYNOPSIS 

finclude <ticlts.h> 
♦include <ticots.h> 
♦include <ticotsord.h> 

DESCRIPTION 

The devices known as ticlts, ticots, and ticotsord are ''loopback transport 
providers/' that is, stand-alone networks at the transport level. Loopback tran- 
sport providers are transport providers in every sense except one: only one host 
(the local machine) is "connected to" a loopback network. Loopback transports 
present a TP! (STREAMS-level) interface to application processes and are intended 
to be accessed via the TLI (application-level) interface. They are implemented as 
clone devices and support address spaces consisting of "flex-addresses/' i.e., arbi- 
trary sequences of octets, of length > 0, represented by a netbuf structure. 

ticlts is a datagram-mode transport provider. It offers (connectionless) service 
of type TJCLTS. Its default address size is TCLJ)EFAULTADDRSZ. ticlts prints 
the following error messages (see t_rcvuderr(3N)): 

TCLJBADADDR bad address specification 

TCL_BADOPT bad option specification 

TCLJNOPEER bound 

TCL_PEERBADSTATE peer in wrong state 

ticots is a virtual circuit-mode transport provider. It offers (connection- 
oriented) service of type T_COTS. Its default address size is TCOJDEFAULTADDRSZ. 
ticots prints the following disconnect messages (see t_rcvdis(3N)): 

TCO_NOPEER no listener on destination address 

TCO__PEERNOROOM0NQ peer has no room on connect queue 

TCOJPEERBADSTATE peer in wrong state 

TCOJPEERINITIATED peer-initiated disconnect 

TCOJPROVIDERINITIATED provider-initiated disconnect 

ticotsord is a virtual circuit-mode transport provider, offering service of type 
T_COTSjORD (connection-oriented service with orderly release). Its default 
address size is TCOOJ)EFAULTADDRSZ. ticotsord prints the following disconnect 
messages (see t_rcvdis(3N)): 

TCXX)_NOPEER no listener on destination address 

TO0O_PEERNORO0M0NQ peer has no room on connect queue 

TCOO_PEERBADSTATE peer in wrong state 

TO0O_PEERINITIATED peer-initiated disconnect 

TCXX)_PR07IDERINITIATED provider-initiated disconnect 



USAGE 



Loopback transports support a local IPC mechanism through the TLI interface. 
Applications implemented in a transport provider-independent manner on a 
client-server model using this IPC are transparently transportable to networked 
environments. 
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Transport provider-independent applications must not include the header files 
listed in the synopsis section above. In particular, the options are (like all tran- 
sport provider options) provider dependent. 

ticlts and ticots support the same service types (TjCLTS and TJCOTS) sup- 
ported by the OSI transport-level model. The use of ticlts and ticots is 
encouraged. 

ticotsord supports the same service type (TjCOTSORD) supported by the TCP/IP 
model. The use of ticotsord is discouraged except for reasons of compatibility. 

FILES 

/dev/ticlts 
/dev/ticots 
/dev/ticotsord 
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NAME 

UDP - Internet User Datagram Protocol 

SYNOPSIS 

tinclude <sys/socket.h> 
tinclude <netinet/in.h> 

S « socket (AP_INET, SOCK_DGRMf, 0) ; 

t = t_ppen("/dev/ud^", OJ<DWR) ; 

DESCRIPTION 

UDP is a simple datagram protocol which is layered directly above the Internet 
Protocol (IP). Programs may access UDP using the socket interface, where it sup- 
ports the SOGKJXSRAM socket type, or using the Transport Level Interface (TLI), 
where it supports the connectionless (TjCLTS) service type. 

Within the socket interface, UDP is normally used with the sendtoO, 
sendmsg( ), recvfrom( ), and recvinsg( ) calls [see send(2) and recv(2)]. If the 
connect(2) call is used to fix the destination for future packets, then the recv(2) 
or read(2) and send(2) or write(2) calls may be used. 

UDP address formats are identical to those used by the Transmission Control Pro- 
tocol (TCP). Like TCP, UDP uses a port number along with an IP address to iden- 
tify the endpoint of communication. The UDP port number space is separate from 
the TCP port number space (that is, a UDP port may not be connected to a TCP 
port). The bind(2) call can be used to set the local address and port number of a 
UDP socket. The local IP address may be left unspecified in the bind ( ) call by 
using the special value INADDRJVNY. If the bind( ) call is not done, a local IP 
address and port number will be assigned to the endpoint when the first packet 
is sent. Broadcast packets may be sent (assuming the underlying network sup- 
ports this) by using a reserved broadcast address; This address is network inter- 
face dependent. Broadcasts may only be sent by the privileged user. 

Options at the IP level may be used with UDP; see ip(7). 

There are a variety of ways that a UDP packet can be lost or corrupted, including 
a failure of the underlying commimication mechanism. UDP implements a check- 
sum over the data portion of the packet. If the checksum of a received packet is 
in error, the packet will be dropped with no indication gyen to the user. A 
queue of received packets is provided for each UDP socket. This queue has a lim- 
ited capacity. Arriving datagrams which will not fit within its high-water capacity 
are silently discarded. 

UDP processes Internet Control Message Protocol (ICMP) error messages received 
in response to UDP packets it has sent. See icarp(7). ICMP source quench mes- 
sages are ignored. ICMP destination unreachable, time exceeded and parameter 
problem messages disconnect the socket from its peer so that subsequent attempts 
to send packets using that socket will return an error. UDP will not guarantee 
that packets are delivered in the order they were sent. As well, duplicate packets 
may be generated in the communication process. 
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SEE ALSO 

read(2), write(2), bindON), connect(3N), recv(3N), sendON), icnp(7), inet(7), 
ip(7), tcp(7). 

Postel, Jon, User Datagram Protocol, RFC 768, Network Information Center, SRI 
International, Menlo Park, Calif., August 1980. 

DIAGNOSTICS 

A socket operation may fail if: 



EISCX>IIN 
EISCONN 

emotconn 

eaddrinuse 
eaddbnotava.il 

EINVAL 
EACCES 

ENOBOFS 



A connect ( ) operation was attempted on a socket on 
which a connect ( ) operation had already been performed, 
and the socket could not be successfully disconnected 
before making the new connection. 

A sendtoC ) or sendmsgC ) operation specifying an address 
to which the message should be sent was attempted on a 
socket on which a connect ( ) operation had already been 
performed. 

A sendO or write () operation, or a sendtoO or 
sendmsgO operation not specifying an address to which 
the message should be sent, was attempted on a socket on 
which a connect ( ) operation had not already been per- 
formed. 

A bind( ) operation was attempted on a socket with a net- 
work address/port pair that has already been boimd to 
another socket. 

A bind( ) operation was attempted on a socket with a net- 
work address for which no network interface exists. 

A sendmsgO operation with a non-NULL xnsg_accrights 
was attempted. 

A bind ( ) operation was attempted with a reserved port 
number and the effective user ID of the process was not the 
privileged user. 

The system ran out of memory for internal data structures. 
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